create-invokta-engine

create-invokta-engine creates one standalone TypeScript Action Engine with a public capability shared by direct invocation and the adapters selected by a closed scaffold profile. It is a binary-only development package, not a runtime adapter or template framework.

Install

Run the current release without adding it to an existing project:

npm create invokta-engine@latest my-engine

The package is native ESM and requires Node.js 22.20.0 or later. The npm initializer maps invokta-engine to the create-invokta-engine package and executable.

Commands

create-invokta-engine [project-directory]
  [--profile complete|mcp-stdio|mcp-http|cli]
  [--package-manager npm|pnpm|yarn]
  [--no-install]
  [--yes]
create-invokta-engine --help
create-invokta-engine --version

Options may appear before or after the one project directory; each option value must immediately follow its option. Duplicates, missing values, unknown options or profiles, --option=value, extra positionals, or combining help or version with another argument are invalid. --yes requires an explicit target.

Interaction modes

Without --yes, the creator is interactive only when standard input and standard error are both TTYs. It asks, in order, for any missing project directory and profile, preflights and plans the full scaffold, then requests one final confirmation naming the normalized relative target, profile, package manager, and installation choice. Nothing is written and no child starts before an affirmative answer. Unicode control, format, line-separator, and paragraph-separator characters in an accepted parent path are escaped in the confirmation instead of being emitted as terminal-active text.

The profile choices are:

1. Complete (CLI + MCP local + MCP HTTP)
2. MCP local (stdio)
3. MCP HTTP
4. CLI

Directory defaults to my-invokta-engine, profile defaults to complete, and confirmation defaults to no. Confirmation accepts case-insensitive y, yes, n, or no after trimming. A negative answer is successful cancellation and writes exactly Creation cancelled. No files were created.

Each answer is strict UTF-8 and at most 4,096 encoded bytes including its line terminator. A byte or decoding violation, or three invalid answers to one question, is PROMPT_INVALID. EOF, interruption, or prompt I/O failure is PROMPT_ABORTED. Diagnostics never echo a rejected answer.

When either stream is not a TTY, the creator never prompts or reads standard input. An explicit target proceeds with the explicit profile or complete; a missing target is INTERACTIVE_REQUIRED before template loading, filesystem mutation, or process execution. This legacy automation remains valid:

create-invokta-engine my-engine --no-install

Pseudo-TTY automation must bypass prompts explicitly:

create-invokta-engine my-engine --profile complete --no-install --yes

Profiles

Profile	Generated channels	Entries
`complete`	Direct, CLI, MCP stdio, MCP HTTP	21
`mcp-stdio`	Direct, MCP stdio	15
`mcp-http`	Direct, MCP HTTP	18
`cli`	Direct, CLI	14

All profiles contain:

.agents/skills/develop-invokta-project/SKILL.md
.agents/skills/develop-invokta-project/agents/openai.yaml
.gitignore
AGENTS.md
CLAUDE.md -> AGENTS.md
README.md
package.json
src/capabilities/create-welcome-message.ts
src/direct.ts
src/engine.ts
test/engine.test.ts
tsconfig.json
tsconfig.test.json

Feature	Added entries	Added packages and scripts
CLI	`src/cli.ts`	`@invokta/cli`; `cli`
MCP local	`invokta.mcp.json`, `src/bin.ts`, `src/mcp-stdio.ts`	`@invokta/installer`, `@invokta/mcp`; `mcp:stdio`, `mcp:install`, `mcp:uninstall`; a project-named `bin` entry and packed `files`
MCP HTTP	`.env.example`, `invokta.deploy.json`, `src/env.ts`, `src/http-auth.ts`, `src/mcp-http.ts`	`@invokta/mcp`, dev `@invokta/deploy`; `mcp:http`, `deploy:package`, `deploy:probe`

Dependencies and scripts are exact set unions. Generated Invokta versions match the creator version. Documentation and generated agent guidance name only the selected channels. Every entry point imports the same engine; direct calls engine.invoke, while CLI and MCP use official adapters that converge on it.

MCP stdio profiles also generate src/bin.ts, a composition root that delegates to @invokta/installer/engine, so an author-prepared package can ship a project-named executable whose install and uninstall commands register or remove the engine without the checkout. Generated projects remain private by default; registry publication requires the author to choose package access and license metadata and remove "private": true explicitly.

MCP HTTP entries are byte-identical to the immutable public planner from @invokta/deploy/scaffold. The creator merges the complete plan before writing, never invokes invokta-deploy init, and contains no copied HTTP template. Generated authentication fails closed until implemented. HTTP profiles ignore .env and .env.* while retaining .env.example.

AGENTS.md records profile-specific architecture and test-first constraints. CLAUDE.md is an actual relative symbolic link to it. The generated develop-invokta-project skill adds project-specific RED/GREEN/REFACTOR and single-engine.invoke guidance without runtime discovery or behavior.

Target and transaction contract

The project directory is relative to the current working directory. Absolute paths and .. segments are rejected. . is accepted when the current directory has a valid lowercase kebab-case name and is empty.

Limit	Value
Project path	At most 1,024 Unicode scalars
Non-dot path segments	At most 32
Project and engine name	Lowercase kebab-case, at most 214 characters

The target may be absent or an empty real directory. A symbolic-link target or component, non-directory, or existing entry fails safely. Planning performs no mutation. After interactive confirmation, the creator revalidates the target, then creates every entry exclusively in lexicographic order. A racing entry is preserved as SCAFFOLD_CONFLICT. A pre-install failure rolls back only paths created by that invocation; rollback failure is WRITE_FAILED. Generated files are deterministic UTF-8 with LF endings and one trailing newline.

Concurrent creation in one target is unsupported. Repeating successful creation fails because the target is no longer empty; profiles are never converted in place.

Package-manager behavior

An explicit --package-manager wins. Otherwise the creator recognizes npm, pnpm, or Yarn from npm_config_user_agent and falls back to npm.

Manager	Install command
npm	`npm install --no-audit --no-fund`
pnpm	`pnpm install`
Yarn	`yarn install`

Exactly one foreground install starts directly without a shell, retry, or creator-owned timeout, and only after every selected entry exists. An unavailable manager, non-zero exit, or signal is INSTALL_FAILED; the generated profile remains for retry. --no-install, prompt failure, and cancellation start no process or network operation. The creator itself never makes a network request.

Output and errors

Help, version, cancellation, and the final profile-aware summary use standard output. Prompts and diagnostics use standard error. The install child inherits terminal streams. No creator output includes rejected input, environment values, credentials, child errors, stacks, or causes.

Exit	Meaning
`0`	Help, version, creation, or normal cancellation succeeded
`1`	Prompt interruption, target safety, filesystem, or installation failed
`2`	Usage, required interaction, prompt input, path, or name was invalid

Code	Meaning
`INTERACTIVE_REQUIRED`	A non-terminal invocation omitted its target
`PROMPT_INVALID`	Prompt bytes, UTF-8, answer, or attempt count was invalid
`PROMPT_ABORTED`	EOF, interruption, or prompt I/O failure ended interaction
`TARGET_INVALID`	Path shape or derived project name was invalid
`TARGET_UNSAFE`	A component was unsafe or could not be inspected
`TARGET_NOT_EMPTY`	The target contained an entry
`SCAFFOLD_CONFLICT`	A planned entry appeared during creation
`WRITE_FAILED`	A scaffold write or rollback failed
`INSTALL_FAILED`	The selected package manager was unavailable or unsuccessful