wizard

Files (50)

• .gitignore
• CREDITS.md
• GLOSSARY.md
• LICENSE
• README.md
• SKILL.md
• openai.yaml · agents/
• cli.ts · engine/
• command.test.ts · engine/
• command.ts · engine/
• discovery.ts · engine/
• execution.ts · engine/
• interactive.ts · engine/fixtures/
• run-interactive.ts · engine/fixtures/
• interaction.ts · engine/
• interactive.test.ts · engine/
• interruption.ts · engine/
• redaction.ts · engine/
• terminal.ts · engine/
• wizard.ts · engine/
• SKILL.md · example/.agents/skills/greet/
• SKILL.md · example/.agents/skills/sign-in/
• engine · example/.agents/skills/wizard/
• SKILL.md · example/.agents/skills/workspace-cache-clear/
• Makefile · example/
• package.json · example/
• command.ts · example/scripts/greet/
• run.ts · example/scripts/greet/
• command.ts · example/scripts/sign-in/
• run.ts · example/scripts/sign-in/
• sign-in.ts · example/scripts/sign-in/
• command.ts · example/scripts/workspace/cache/clear/
• run.ts · example/scripts/workspace/cache/clear/
• package-lock.json
• package.json
• README.md · recordings/
• interactive-force-stop.cast · recordings/
• interactive-force-stop.gif · recordings/
• interactive-sign-in.cast · recordings/
• interactive-sign-in.gif · recordings/
• light.cast · recordings/
• long-menu.cast · recordings/
• narrow.cast · recordings/
• no-color.cast · recordings/
• raw-interrupt.cast · recordings/
• raw-interrupt.gif · recordings/
• record-interactive.mjs · recordings/
• static.cast · recordings/
• wizard.cast · recordings/
• tsconfig.json

SKILL.md (first lines)

# Wizard

Install one engine and give each command one declaration. Raw Make targets, interactive wizards, and command skills all reach the same command code. This applies to every script operation, including queries, reports, maintenance, builds, and setup.

Read [README.md](README.md) for the runnable example and terminal settings. Read [GLOSSARY.md](GLOSSARY.md) when distinguishing commands, namespaces, inputs, and human stages.

## Wire a repository

1. Inspect the repository's scripts, Make targets, package manager, and skill directory. Inventory every script operation and map each to a command path. Preserve the existing process logic behind the command's `run` function. Each operation has a raw target, wizard entry, and command skill before this step is complete.
2. Install this entire folder as `.agents/skills/wizard/` and keep the engine there. Install its runtime dependencies with `npm ci --omit=dev --prefix .agents/skills/wizard`. Ignore `.agents/skills/wizard/node_modules/`. Commit or reproducibly install the skill folder and its lockfile. Updating the installed skill upgrades the shared engine; keep repository-specific logic under `scripts/`.
3. Require Node 24 and ESM (`"type": "module"` in the repository's package manifest). Add this package import so commands at every depth use the same path:

   ```json
   {
     "imports": { "#wizard": "./.agents/skills/wizard/engine/command.ts" }
   }
   ```

4. Add these Make rules. Merge the declarations with existing conventions. The command list comes from the filesystem. Keep the raw rule a **static pattern rule** with the discovered targets before `%: scripts/%/run.ts`. A bare implicit `%` rule resolves nested paths incorrectly.

```make
.DEFAULT_GOAL := wizard
WIZARD_ENGINE := .agents/skills/wizard/engine
COMMANDS := $(shell node $(WIZARD_ENGINE)/cli.ts list-commands)
.EXPORT_ALL_VARIABLES:
.PHONY: wizard check-commands $(COMMANDS)

wizard:
	@node $(WIZARD_ENGINE)/cli.ts wizard

%/wizard:
	@node $(WIZARD_ENGINE)/cli.ts wizard $*

$(COMMANDS): %: scripts/%/run.ts
	@node $<

check-commands:
	@node $(WIZARD_ENGINE)/cli.ts check-commands
```

   Recipes use literal tab indentation. Variables reach Node through the environment; keep input expansions such as `$(SQL)` out of recipe text. Paths contain lowercase kebab-case segments. Reserve the segment `wizard` and the root path `check-commands`. Every folder containing either entry file must contain both entry files. Namespace folders contain descendants and need no declaration.

5. Add the TypeScript 7 compiler (`@typescript/native-preview`, pinned to the version in this skill's package manifest) and Node 24 types to the repository's development dependencies. Typecheck the consuming scripts and installed engine together. Exclude `.agents/skills/wizard/engine/**/*.test.ts` from the consuming repository typecheck; the skill runs its tests with its own development dependencies. Use `strict`, `module: "NodeNext"`, `noEmit`, `allowImportingTsExtensions`, `verbatimModuleSyntax`, and `erasableSyntaxOnly`. Node runs `.ts` files directly. Use erasable syntax and explicit `.ts` import extensions.

Complete wiring when `make check-commands`, the repository typecheck, a raw command, `make wizard`, and a nested namespace wizard pass. Exercise cancellation and a fake secret in the installed layout.

## Add a command

Create `scripts/<path>/command.ts` and a thin `run.ts`. Export `definition` from the declaration. Keep module initialization and all transitive imports free of side effects; discovery imports declarations. Load costly dependencies inside `run`.

```typescript
// scripts/db/read/command.ts
import type { Command } from '#wizard';

export const definition = {
  name: 'Read records',
  help: 'Run a read-only query.',
  inputs: [{
    name: 'SQL',
    prompt: 'Which query should run?',
    help: 'Enter a read-only SQL statement.',
    required: true,
    secret: false,
    kind: 'text',
    default: 'SELECT 1',
  }],
  async run(inputs, { root }) {
    const { readRecords } = await import('./read-records.ts');
    return readRecords(String(inputs.SQL), root);
  },
} satisfies Command;
```

```typescript
// scripts/db/read/run.ts
import { runCommand } from '#wizard';
import { definition } from './command.ts';

await runCommand(definition);
```

`run` receives validated inputs and a `CommandContext` with `root`, `signal`, and `terminal`, and returns a result string. Perform all command work there. Return output instead of printing it. Run subprocesses with closed stdin and captured output so the wizard owns interaction. Await subprocess completion and keep descendants in the command process group.

Each input declares `name`, `prompt`, `help`, `required`, `secret`, and `kind`. Names are uppercase Make variable names. The checker rejects execution-control names such as `PATH`, `SHELL`, `MAKEFLAGS`, `NODE_OPTIONS`, and `WIZARD_*`. Use a descriptive name such as `ACCOUNT_NAME` rather than an ambient shell name such as `USER`.

| Kind | Value | Optional declaration |
|---|---|---|
| `text` | String | `default: 'value'` |
| `choice` | One declared option value | `options: [{ value: 'safe', label: 'Safe' }]`, `default: 'safe'` |
| `confirm` | Boolean | `default: false` |
| `number` | Finite number | `default: 1` |

`choice` requires nonempty, unique options. Defaults must match the kind and allowed choices. Omitted optional inputs use their default when declared, otherwise `''`. An explicit Skip on an optional choice yields `''` even when it has a default. A required input can have a default. Keep real credentials out of declarations and defaults. `secret: true` uses hidden entry for every kind; its help must explain the expected format or choice values.

Add business validation inside `run`, such as integer bounds or read-only query restrictions. Raw targets and wizards share that validation. An input's `required` flag checks presence; `false` remains a valid confirmation input.

For irreversible actions, set `irreversible` to a precise consequence, including the affected resource. The wizard asks for confirmation with cancel selected. The raw runner requires `CONFIRM=true`; the closing command includes it after confirmation. Human stages run before inputs and execution, one at a time:

```typescript
stages: [{ name: 'Review the resource', help: 'Finish work that needs the selected resource before removing it.' }],
irreversible: 'This permanently removes the selected resource.',
```

Stages describe work only a human can do, and pause for explicit completion. Raw operators and agents complete these prerequisites themselves. Use interactive execution when a command needs typed input between automated operations. Consult the [terminal reference](README.md#terminal-behavior) for interruption behavior.

## Run an interactive command

Set `interactive: true` when command work asks questions or needs cancellable progress. Omission means false; supplied values must be boolean. The wizard completes declaration inputs, human stages, and irreversible confirmation, then calls `run` in process with `wizard: true`. Raw execution calls the same definition without that flag. Existing commands keep their child execution in the wizard and Node's default SIGINT handling in raw execution.

Use only the context's terminal methods for command prompts. They share the engine's prompt instance and cancellation signal. Check `process.stdin.isTTY && process.stdout.isTTY` before asking human questions. Keep piped output machine-readable; progress is silent when stdout is redirected.

```typescript
async run(inputs, { signal, terminal }) {
  await requestCode(String(inputs.EMAIL), signal);

  const code = await terminal.password('Enter the code', value => {
    const missingCode = !value?.trim();

    if (missingCode) return 'Enter the code from your email.';

From Camgineer/skills, Apache-2.0.

More from Camgineer/skills