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, or imports a public GitHub example tree as the project template. It can also generate selected capability candidates from one local OpenAPI 3.1.x contract. 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]
  [--example <name|github-url>]
  [--example-path <subdir>]
  [--openapi <local-json-or-yaml-file>]
  [--exclude <operation-id|METHOD:/path>]...
  [--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, combining --example with --profile or --openapi, using --example-path without --example, using --exclude without --openapi, or combining help or version with another argument are invalid. --yes requires an explicit target. OpenAPI import may use any profile.

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. When --example is present it skips the profile prompt and confirms the example label instead. 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.

With --openapi, the creator displays a deterministic operation catalog. Every eligible endpoint is selected by default; unsupported endpoints remain visible and unselected with one stable reason. The exclusion prompt accepts a comma-separated list of eligible row numbers, and an empty answer keeps every eligible endpoint. Automation can repeat --exclude with a unique operationId or canonical METHOD:/path selector.

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, dev @invokta/tooling; check: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 and @invokta/tooling; check:mcp, 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.

For every MCP profile, the canonical generated check builds the engine and runs invokta check-mcp ./dist/engine.js. The preflight constructs the final MCP catalog without starting a transport and rejects ambiguous derived tool names before installation or deployment. The CLI-only profile omits this gate.

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. It also guides authors to keep external integrations behind engine-owned ports and use defineConnector for typed private configuration, explicit dependencies, bounded cancellation-aware work, sanitized failures, and port-only injection.

GitHub example import

--example bootstraps from a public GitHub repository instead of a closed profile scaffold, similar to create-next-app --example:

create-invokta-engine my-engine --example auth-clerk-engine --no-install --yes
create-invokta-engine my-engine \
  --example https://github.com/acme/engine-template \
  --no-install --yes
create-invokta-engine my-engine \
  --example https://github.com/acme/repo/tree/main/templates/engine \
  --no-install --yes

Official short names resolve to vinilana/invokta examples/<name> on main. HTTPS github.com repository and tree URLs resolve owner, repository, ref, and optional subdirectory. --example-path supplies or overrides the subdirectory when the URL cannot encode it cleanly.

Before confirmation the creator verifies that package.json exists at the example root. After confirmation it downloads only from codeload.github.com, extracts the selected subtree, rewrites package.json name to the project directory name, and copies regular files through the same exclusive-create and rollback boundary. Archive symbolic links, hard links, and path escapes are rejected. Private repositories, SSH, tokens, and non-GitHub hosts are out of scope. Dependency completeness belongs to the template author.

OpenAPI capability import

--openapi reads one local OpenAPI 3.1.x JSON or YAML entry document and generates ordinary TypeScript capability candidates for selected supported HTTP operations:

create-invokta-engine my-engine \
  --profile cli \
  --openapi ./openapi.yaml \
  --exclude deleteAccount \
  --exclude 'POST:/internal/reindex' \
  --no-install \
  --yes

The bounded importer resolves only contained local references. It never fetches a remote document, contacts the described API, invokes an operation, or reads a credential. It infers declared server precedence and variable defaults, parameter locations and serialization, JSON request and success responses, and anonymous, API-key, Basic, or Bearer upstream authentication. Combined security schemes must target distinct request locations. Generated credentials are environment-variable names only.

Generated request paths remain confined to the configured base URL origin, and the runtime validates that origin before applying credentials or calling fetch. Generated module basenames are portable ASCII, avoid Windows device names, and are at most 64 characters. Unsupported operations remain visible and are never weakened into generated code.

The result is a source-generated starting point, not a trusted API mirror. Review each capability’s domain meaning, name, access rule, upstream base URL, and credential handling before deployment.

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 project remains for retry. --no-install starts no package manager. Profile creation and OpenAPI analysis perform no creator-owned network request. Example import may contact api.github.com and codeload.github.com only, even when --no-install is set.

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, import, or installation failed
2	Usage, required interaction, prompt input, path, name, or import input 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
EXAMPLE_INVALID	The example name, URL, or path was invalid
EXAMPLE_UNAVAILABLE	The example could not be resolved or downloaded
EXAMPLE_FAILED	Example extraction or target copy failed
OPENAPI_INVALID	The OpenAPI 3.1.x document or import arguments were invalid
OPENAPI_UNAVAILABLE	The local OpenAPI document could not be read
OPENAPI_UNSUPPORTED	The document had no supported operation to import
OPENAPI_SELECTION_INVALID	An exclusion was unknown, ambiguous, unsupported, or removed every eligible operation
OPENAPI_LIMIT_EXCEEDED	The import crossed a documented byte, document, node, operation, selection, or generated-name limit