wabachi 0.1.0 → 0.2.1

package/dist/skill.d.ts

@@ -0,0 +1,47 @@
+import { type CommandId } from "./command-contract.js";
+/** Deterministic intent-oriented playbooks for the supported Wabachi surface. */
+export declare const SKILL_MODEL_VERSION: "1.0.0";
+export declare const MAX_SKILL_OUTPUT_BYTES = 4096;
+export interface SkillWorkflowStep {
+    readonly summary: string;
+    /** Stable reference into the versioned command contract. */
+    readonly commandId: CommandId;
+    /** Bare executable command derived from commandId. */
+    readonly command: string;
+    /** Practical example derived from commandId. */
+    readonly example: string;
+    /** Progressive-help pointer derived from commandId. */
+    readonly helpPointer: string;
+}
+export interface SkillScenario {
+    readonly id: string;
+    readonly title: string;
+    readonly whenToUse: string;
+    readonly workflow: readonly SkillWorkflowStep[];
+    readonly invariants: readonly string[];
+    readonly canonicalCommandId: CommandId;
+    readonly canonicalEntrypoint: string;
+    readonly helpPointer: string;
+}
+export declare const SKILL_SCENARIOS: readonly SkillScenario[];
+export interface SkillIndexEntry {
+    readonly id: string;
+    readonly title: string;
+    readonly whenToUse: string;
+}
+export interface SkillIndexProjection {
+    readonly version: typeof SKILL_MODEL_VERSION;
+    readonly scenarios: readonly SkillIndexEntry[];
+}
+export interface SkillScenarioProjection extends SkillScenario {
+    readonly version: typeof SKILL_MODEL_VERSION;
+}
+export declare function findSkillScenario(id: string): SkillScenario | undefined;
+export declare function projectSkillIndexToJson(): SkillIndexProjection;
+export declare function projectSkillIndexToText(): string;
+export declare function projectSkillScenarioToJson(scenario: SkillScenario): SkillScenarioProjection;
+export declare function projectSkillScenarioToText(scenario: SkillScenario): string;
+/** Keep text diagnostics and projections within the explicit UTF-8 budget. */
+export declare function boundText(value: string): string;
+/** Serialize a JSON projection without allowing the machine-readable path to exceed the same cap. */
+export declare function serializeSkillJson(value: unknown): string;

package/dist/skill.js

@@ -0,0 +1,160 @@
+import { commandExample, commandHelpPointer, commandInvocation, getCommand, } from "./command-contract.js";
+/** Deterministic intent-oriented playbooks for the supported Wabachi surface. */
+export const SKILL_MODEL_VERSION = "1.0.0";
+export const MAX_SKILL_OUTPUT_BYTES = 4096;
+function workflowStep(summary, commandId) {
+    getCommand(commandId);
+    return {
+        summary,
+        commandId,
+        command: commandInvocation(commandId),
+        example: commandExample(commandId),
+        helpPointer: commandHelpPointer(commandId),
+    };
+}
+function skillScenario(input) {
+    return {
+        id: input.id,
+        title: input.title,
+        whenToUse: input.whenToUse,
+        workflow: input.workflow.map(([summary, commandId]) => workflowStep(summary, commandId)),
+        invariants: input.invariants,
+        canonicalCommandId: input.canonicalCommandId,
+        canonicalEntrypoint: commandInvocation(input.canonicalCommandId),
+        helpPointer: commandHelpPointer(input.canonicalCommandId),
+    };
+}
+export const SKILL_SCENARIOS = [
+    skillScenario({
+        id: "analyze-repository",
+        title: "Analyze a repository",
+        whenToUse: "Use when you need deterministic provider output for a repository at a selected revision.",
+        workflow: [["Resolve the repository and execute the registered analysis providers.", "run.execute"]],
+        invariants: [
+            "Choose an explicit revision when reproducibility matters; the default resolution remains supported.",
+            "Retain the output directory when another workflow or reviewer needs the manifest and provider artifacts.",
+            "The provider set and analysis execution semantics are owned by the runtime, not this playbook.",
+        ],
+        canonicalCommandId: "run.execute",
+    }),
+    skillScenario({
+        id: "provider-matrix",
+        title: "Build a provider matrix",
+        whenToUse: "Use when you need auditable facts, correlations, matrix output, and a report for one revision.",
+        workflow: [["Run the provider matrix and retain its generated artifacts.", "matrix.execute"]],
+        invariants: [
+            "Use a 40-character commit SHA when matrix evidence must be tied to an immutable revision.",
+            "Provide an output directory so the report and its supporting artifacts remain inspectable.",
+            "Provider registration and matrix execution order remain runtime authority.",
+        ],
+        canonicalCommandId: "matrix.execute",
+    }),
+    skillScenario({
+        id: "validate-architecture-canon",
+        title: "Validate an Architecture Canon",
+        whenToUse: "Use before rendering an explicit Architecture Canon document or handing it to another workflow.",
+        workflow: [["Validate the explicit Canon file and inspect any bounded diagnostics.", "architecture.validate"]],
+        invariants: [
+            "The Canon file is explicit input; this workflow does not create or mutate one.",
+            "Validation must succeed before rendering or publishing derived documentation.",
+            "Machine-readable diagnostics are available through the command's JSON projection.",
+        ],
+        canonicalCommandId: "architecture.validate",
+    }),
+    skillScenario({
+        id: "render-architecture-canon",
+        title: "Render Architecture Canon documentation",
+        whenToUse: "Use when a valid Architecture Canon should become a retained static documentation site.",
+        workflow: [["Render the explicit Canon file into a retained output directory.", "architecture.render"]],
+        invariants: [
+            "Validate the same Canon file first when its validity has not already been established.",
+            "The Structurizr CLI is required for static export; use the command's executable override only when needed.",
+            "Rendering is a projection and does not add an Architecture Canon authoring command.",
+        ],
+        canonicalCommandId: "architecture.render",
+    }),
+    skillScenario({
+        id: "architecture-documentation",
+        title: "Follow the Architecture Documentation workflow",
+        whenToUse: "Use for the normal manual-authoring, validation, and rendering path for Architecture Canon documentation.",
+        workflow: [
+            [
+                "Author or revise the explicit Canon document using repository documentation guidance; no init command is implied.",
+                "architecture.help",
+            ],
+            ["Validate the authored Canon before producing derived documentation.", "architecture.validate"],
+            ["Render the validated Canon into a retained static site.", "architecture.render"],
+        ],
+        invariants: [
+            "Authoring remains a deliberate file-editing step; Wabachi does not invent an init or edit command.",
+            "Validation and rendering operate on an explicit Canon file and preserve existing execution semantics.",
+            "Keep the generated site and source Canon together when the result is intended for review or publication.",
+        ],
+        canonicalCommandId: "architecture.help",
+    }),
+];
+export function findSkillScenario(id) {
+    return SKILL_SCENARIOS.find((scenario) => scenario.id === id);
+}
+export function projectSkillIndexToJson() {
+    return {
+        version: SKILL_MODEL_VERSION,
+        scenarios: SKILL_SCENARIOS.map(({ id, title, whenToUse }) => ({ id, title, whenToUse })),
+    };
+}
+export function projectSkillIndexToText() {
+    const lines = [`Wabachi skill scenarios (v${SKILL_MODEL_VERSION}):`, ""];
+    for (const scenario of SKILL_SCENARIOS) {
+        lines.push(`  ${scenario.id} - ${scenario.title}`);
+        lines.push(`    ${scenario.whenToUse}`);
+    }
+    lines.push("", "Run `wabachi skill <scenario>` for one bounded playbook.");
+    return boundText(lines.join("\n"));
+}
+export function projectSkillScenarioToJson(scenario) {
+    return {
+        version: SKILL_MODEL_VERSION,
+        ...scenario,
+        workflow: scenario.workflow.map((step) => workflowStep(step.summary, step.commandId)),
+    };
+}
+export function projectSkillScenarioToText(scenario) {
+    const projected = projectSkillScenarioToJson(scenario);
+    const lines = [`${projected.title} (${projected.id})`, "", `When to use: ${projected.whenToUse}`, "", "Workflow:"];
+    projected.workflow.forEach((step, index) => {
+        lines.push(`  ${index + 1}. ${step.summary}`);
+        lines.push(`     Command: ${step.command}`);
+        lines.push(`     Example: ${step.example}`);
+        lines.push(`     Help: ${step.helpPointer}`);
+    });
+    lines.push("", "Invariants:");
+    for (const invariant of projected.invariants)
+        lines.push(`  - ${invariant}`);
+    lines.push("", `Canonical entrypoint: ${projected.canonicalEntrypoint}`, `Exact syntax: ${projected.helpPointer}`);
+    return boundText(lines.join("\n"));
+}
+/** Keep text diagnostics and projections within the explicit UTF-8 budget. */
+export function boundText(value) {
+    if (Buffer.byteLength(value, "utf8") <= MAX_SKILL_OUTPUT_BYTES)
+        return value;
+    const suffix = "…";
+    const characters = Array.from(value);
+    while (characters.length > 0 &&
+        Buffer.byteLength(`${characters.join("")}${suffix}`, "utf8") > MAX_SKILL_OUTPUT_BYTES) {
+        characters.pop();
+    }
+    return `${characters.join("")}${suffix}`;
+}
+/** Serialize a JSON projection without allowing the machine-readable path to exceed the same cap. */
+export function serializeSkillJson(value) {
+    const serialized = JSON.stringify(value);
+    if (Buffer.byteLength(serialized, "utf8") <= MAX_SKILL_OUTPUT_BYTES)
+        return serialized;
+    return JSON.stringify({
+        ok: false,
+        diagnostics: [
+            { code: "skill-output-too-large", message: `skill output exceeds ${MAX_SKILL_OUTPUT_BYTES} UTF-8 bytes` },
+        ],
+    });
+}
+//# sourceMappingURL=skill.js.map

package/dist/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}

package/docs/USAGE.md

@@ -0,0 +1,110 @@
+# Wabachi usage
+
+Wabachi is a deterministic repository-analysis and Architecture Canon CLI.
+This manual explains the normal workflows for people. The installed command
+contract is authoritative: use `wabachi --help`, progressive command help, and
+`wabachi skill` for the exact current syntax.
+
+## Install and discover
+
+Wabachi requires Node.js 24 or newer.
+
+```bash
+npm install --global wabachi
+wabachi --version
+wabachi --help
+```
+
+For an ephemeral run, use `npx --yes wabachi --help`. Agents can begin with
+`wabachi skill` and then request one bounded playbook with
+`wabachi skill <scenario>`. Add `--json` to skill or help when consuming the
+projection from a script.
+
+## Analyze a repository
+
+`run` resolves a repository and executes the registered analysis providers. It
+can use the default revision resolution or an explicit revision, and writes a
+manifest plus provider output under a temporary directory unless `--out` is
+provided.
+
+```bash
+wabachi run .
+wabachi run . --revision HEAD --out ./artifacts/run
+```
+
+Use a commit SHA or another stable ref when the result will be compared or
+reviewed. The command prints the manifest path. Keep the directory named by
+`--out` if downstream work needs the facts or provider outputs.
+
+## Build a provider matrix
+
+`matrix` runs the matrix workflow for one revision and requires retained output
+artifacts. A full 40-character commit SHA is the safest input for reproducible
+evidence.
+
+```bash
+wabachi matrix . --revision 0123456789abcdef0123456789abcdef01234567 --out ./artifacts/matrix
+```
+
+The command prints the report path. The output directory also contains the
+supporting facts and correlation artifacts used to produce the report. For a
+configured provider workflow, pass a JSON configuration file with the source,
+revision, provider IDs, and addition order:
+
+```bash
+wabachi matrix --config ./matrix-workflow.json
+```
+
+The configured provider set must match the providers registered by the
+installed Wabachi version.
+
+## Architecture Canon
+
+Architecture Canon authoring is an explicit file-editing step. Wabachi does
+not provide an init or edit command. Create or revise the Canon document using
+the repository's documented schema, then validate it before rendering.
+
+```bash
+wabachi architecture validate ./architecture.json
+wabachi architecture validate ./architecture.json --json
+```
+
+Rendering requires the Structurizr CLI. Wabachi writes the generated site and
+static diagrams beneath the directory passed to `--out`:
+
+```bash
+wabachi architecture render ./architecture.json --out ./artifacts/site
+```
+
+If `structurizr` is not on `PATH`, provide one executable identity without
+changing the workflow:
+
+```bash
+wabachi architecture render ./architecture.json \
+  --out ./artifacts/site \
+  --structurizr-command /opt/structurizr/structurizr.sh
+```
+
+The normal documentation path is: author the explicit Canon, validate that
+same file, then render it into a retained site. The matching live playbook is
+`wabachi skill architecture-documentation`.
+
+## Common failures and recovery
+
+- If a repository cannot be resolved, confirm the path or remote and retry
+  `run` with an explicit revision. Preserve the printed diagnostic when the
+  failure needs investigation.
+- If `matrix` rejects a revision, use a full commit SHA and provide `--out`.
+  If a configuration is rejected, compare its provider IDs and addition order
+  with the installed provider set.
+- If Canon validation fails, fix the reported document issue and validate the
+  same file again before rendering. `--json` is useful for automation.
+- If rendering fails before export, validate the Canon and check that the
+  Structurizr executable can run. Use `--structurizr-command` for a deliberate
+  executable override and inspect the retained output directory.
+- If syntax is uncertain, stop relying on a copied example and resolve the
+  current contract with `wabachi architecture --help` or the relevant leaf
+  help. Unsupported commands fail closed.
+
+Generated outputs are ordinary retained files; Wabachi does not publish them
+or activate an agent plugin as a side effect of npm installation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wabachi",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Repository analysis and Architecture Canon tooling for deterministic codebase understanding.",
   "type": "module",
   "bin": {
@@ -9,23 +9,11 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/USAGE.md",
+    "skills",
+    ".codex-plugin"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/chmod-bin.mjs",
-    "start": "node dist/index.js",
-    "test": "node --test --import tsx src/**/*.test.ts scripts/**/*.test.mjs",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint 'src/**/*.ts' 'scripts/**/*.mjs' 'eslint.config.mjs'",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "smoke-test": "node scripts/smoke-test.mjs",
-    "test:package": "pnpm run build && node scripts/run-package-suite.mjs",
-    "governance:actions": "node scripts/validate-action-pins.mjs",
-    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm test && pnpm run governance:actions && pnpm run test:package",
-    "prepack": "pnpm run build",
-    "prepublishOnly": "pnpm run typecheck && pnpm test"
-  },
   "dependencies": {
     "@sourcegraph/scip-typescript": "0.4.0",
     "typescript": "^6.0.3"
@@ -39,9 +27,8 @@
     "typescript-eslint": "8.67.0"
   },
   "engines": {
-    "node": ">=22.13"
+    "node": ">=24"
   },
-  "packageManager": "pnpm@11.18.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -68,5 +55,18 @@
     "ai-agents"
   ],
   "main": "dist/index.js",
-  "types": "./dist/index.d.ts"
-}
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/chmod-bin.mjs",
+    "start": "node dist/index.js",
+    "test": "node --test --import tsx src/**/*.test.ts scripts/**/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.ts' 'scripts/**/*.mjs' 'eslint.config.mjs'",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "smoke-test": "node scripts/smoke-test.mjs",
+    "test:package": "pnpm run build && node scripts/run-package-suite.mjs",
+    "governance:actions": "node scripts/validate-action-pins.mjs",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm test && pnpm run governance:actions && pnpm run test:package"
+  }
+}

package/skills/wabachi/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: wabachi
+description: |
+  Use Wabachi for deterministic repository analysis, provider matrices, and
+  Architecture Canon validation or rendering. Resolve current workflows and
+  exact syntax through the live CLI.
+---
+
+# Wabachi
+
+This bundled Skill is a routing entrypoint. The installed CLI is the authority
+for command syntax and operational playbooks; this file intentionally does not
+duplicate flags or workflow details.
+
+Start with:
+
+```bash
+wabachi skill
+wabachi --help
+```
+
+Then choose a bounded intent with `wabachi skill <scenario>`. Resolve exact
+syntax for each command through its progressive help pointer, for example:
+
+```bash
+wabachi architecture --help
+wabachi architecture validate --help
+```
+
+Use `--json` on `skill` or help when a machine-readable projection is needed.