code-ai-installer 3.0.0 → 4.0.0

package/dist/shared/tools.js

@@ -0,0 +1,413 @@
+import { z } from "zod";
+import { ArtifactClass, ClassificationOutcome, DomainId, GateName, PipelineMode, Signer, SkillType, } from "./vocabulary.js";
+import { AgentName, RoleFrontmatter, SkillFrontmatter, SkillName } from "./frontmatter.js";
+import { PersonaMerged } from "./persona.js";
+/**
+ * MCP tool I/O contracts — one schema pair per tool.
+ *
+ * Each tool exports `<ToolName>Input` and `<ToolName>Output` zod schemas.
+ * The MCP server (packages/mcp) uses these for runtime validation; consumers
+ * (claude code, tests) get typed call signatures via z.infer.
+ *
+ * Phase 1 baseline (18 tools) — from packages/mcp/README.md.
+ * Phase 2 dev-domain (8 tools) — stubbed at the end.
+ */
+// ─── Shared helpers ──────────────────────────────────────────────────────────
+/** Stable task id (one ongoing task = one classify→advance→sign-off thread). */
+export const TaskId = z.string().min(1);
+/** ADR identifier — "ADR-{domain}-{ordinal}" or supersedes-style "ADR-CC-2-001". */
+export const AdrId = z.string().min(1).regex(/^ADR-[A-Z0-9]+(-[A-Z0-9]+)+$/);
+/** Generic options for request_decision. */
+export const DecisionOption = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    tradeoffs: z.array(z.string()).default([]),
+});
+/** A single error item for structured exception output. */
+export const ExceptionItem = z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+    evidence: z.unknown().optional(),
+});
+// ════════════════════════════════════════════════════════════════════════════
+// PHASE 1 — BASELINE TOOLS
+// ════════════════════════════════════════════════════════════════════════════
+// ─── load_role ────────────────────────────────────────────────────────────────
+export const LoadRoleInput = z.object({
+    role_name: AgentName,
+    domain: DomainId,
+});
+export const LoadRoleOutput = z.object({
+    role: RoleFrontmatter,
+    role_body: z.string(),
+    persona: PersonaMerged,
+    tool_allowlist: z.array(z.string()),
+    available_skills: z.array(SkillName),
+});
+// ─── list_skills ──────────────────────────────────────────────────────────────
+export const ListSkillsInput = z.object({
+    domain: DomainId.optional(),
+    type: SkillType.optional(),
+    gate: GateName.optional(),
+    tech: z.string().optional(),
+    topic: z.string().optional(),
+    owner: AgentName.optional(),
+});
+export const ListSkillsOutput = z.object({
+    skills: z.array(z.object({
+        name: SkillName,
+        description: z.string(),
+        type: SkillType,
+        gates: z.array(GateName),
+    })),
+});
+// ─── get_skill ───────────────────────────────────────────────────────────────
+export const GetSkillInput = z.object({
+    name: SkillName,
+    domain: DomainId,
+});
+export const GetSkillOutput = z.object({
+    frontmatter: SkillFrontmatter,
+    body: z.string(),
+});
+// ─── request_decision (the only decision channel) ────────────────────────────
+export const RequestDecisionInput = z.object({
+    task_id: TaskId,
+    gate: GateName,
+    question: z.string().min(1),
+    options: z.array(DecisionOption).min(2),
+    context: z.string().optional(),
+});
+export const RequestDecisionOutput = z.object({
+    chosen_option_id: z.string().min(1),
+    signer: Signer,
+    /** ADR auto-recorded for every decision; client need not call record_decision separately. */
+    adr_id: AdrId,
+    timestamp: z.string(),
+});
+// ─── record_decision (atomic write to 3 places) ──────────────────────────────
+export const RecordDecisionInput = z.object({
+    task_id: TaskId,
+    gate: GateName,
+    question: z.string().min(1),
+    options: z.array(DecisionOption),
+    chosen_option_id: z.string().min(1),
+    rationale: z.string().min(1),
+    signer: Signer,
+    supersedes: AdrId.optional(),
+});
+export const RecordDecisionOutput = z.object({
+    adr_id: AdrId,
+    adr_path: z.string(),
+    drawer_id: z.string(),
+    kg_triple_id: z.string(),
+});
+// ─── classify_gate (mandatory before producing artifact) ─────────────────────
+export const ClassifyGateInput = z.object({
+    task_id: TaskId,
+    gate: GateName,
+    outcome: ClassificationOutcome,
+    rationale: z.string().min(1),
+});
+export const ClassifyGateOutput = z.object({
+    acknowledged: z.literal(true),
+    next_required_action: z.enum([
+        "produce_artifact",
+        "open_request_decision",
+        "open_report_exception",
+    ]),
+});
+// ─── advance_gate (state machine transition) ────────────────────────────────
+export const AdvanceGateInput = z.object({
+    task_id: TaskId,
+    mode: PipelineMode,
+    from_gate: GateName,
+    to_gate: GateName,
+    handoff_string: z.string().min(1).max(4000),
+});
+export const AdvanceGateOutput = z.object({
+    task_id: TaskId,
+    current_gate: GateName,
+    /** Tool allowlist for the new gate's authorized role. */
+    allowed_tools: z.array(z.string()),
+});
+// ─── current_gate ────────────────────────────────────────────────────────────
+export const CurrentGateInput = z.object({
+    task_id: TaskId,
+});
+export const CurrentGateOutput = z.object({
+    mode: PipelineMode,
+    gate: GateName,
+    allowed_tools: z.array(z.string()),
+    required_handoff_fields: z.array(z.string()),
+    classification_pending: z.boolean(),
+});
+// ─── sign_off ────────────────────────────────────────────────────────────────
+export const SignOffInput = z.object({
+    task_id: TaskId,
+    gate: GateName,
+    signer: Signer,
+    /** Evidence — for mcp signer this is the auto_check tool output; for den it's free-form. */
+    evidence: z.unknown().optional(),
+});
+export const SignOffOutput = z.object({
+    signed: z.literal(true),
+    signer: Signer,
+    timestamp: z.string(),
+});
+// ─── submit_artifact ─────────────────────────────────────────────────────────
+export const SubmitArtifactInput = z.object({
+    task_id: TaskId,
+    class: ArtifactClass,
+    path: z.string().min(1),
+    content: z.string(),
+    /** Required for class="skill"/"role" — frontmatter validated against the corresponding schema. */
+    frontmatter: z.unknown().optional(),
+    /**
+     * Optional gate this artifact was produced at. When provided, submit_artifact
+     * appends an entry to the per-task artifacts index (.code-ai/state/artifacts/
+     * <task_id>.jsonl) so list_artifacts / get_artifact can locate it by gate.
+     * Existing callers that omit `gate` keep working — the file is still written,
+     * just not indexed by gate.
+     */
+    gate: GateName.optional(),
+});
+export const SubmitArtifactOutput = z.object({
+    written: z.literal(true),
+    path: z.string(),
+    line_count: z.number().int().nonnegative(),
+    cap: z.number().int().nullable(),
+});
+// ─── verify_claim ────────────────────────────────────────────────────────────
+export const VerifyClaimInput = z.object({
+    task_id: TaskId,
+    claim_type: z.enum([
+        "tests_pass",
+        "build_succeeds",
+        "lint_clean",
+        "no_orphan_skills",
+        "owners_present",
+        "vocab_valid",
+        "custom",
+    ]),
+    args: z.record(z.string(), z.unknown()).default({}),
+});
+export const VerifyClaimOutput = z.object({
+    verified: z.boolean(),
+    evidence: z.unknown(),
+    failures: z.array(ExceptionItem).default([]),
+});
+// ─── report_exception (exception-only channel) ───────────────────────────────
+export const ReportExceptionInput = z.object({
+    task_id: TaskId,
+    gate: GateName,
+    what_failed: z.string().min(1),
+    breakdown: z.array(ExceptionItem).min(1),
+});
+export const ReportExceptionOutput = z.object({
+    exception_id: z.string(),
+    surfaced_to: Signer,
+});
+// ─── get_artifact ────────────────────────────────────────────────────────────
+export const GetArtifactInput = z.object({
+    task_id: TaskId,
+    gate: GateName,
+    format: z.enum(["raw", "summary"]).default("raw"),
+});
+export const GetArtifactOutput = z.object({
+    exists: z.boolean(),
+    path: z.string().optional(),
+    content: z.string().optional(),
+});
+// ─── list_artifacts ──────────────────────────────────────────────────────────
+export const ListArtifactsInput = z.object({
+    task_id: TaskId,
+});
+export const ListArtifactsOutput = z.object({
+    artifacts: z.array(z.object({
+        gate: GateName,
+        class: ArtifactClass,
+        path: z.string(),
+        line_count: z.number().int().nonnegative(),
+    })),
+});
+// ─── audit_trail ─────────────────────────────────────────────────────────────
+export const AuditTrailInput = z.object({
+    task_id: TaskId,
+});
+export const AuditTrailOutput = z.object({
+    events: z.array(z.object({
+        timestamp: z.string(),
+        kind: z.enum([
+            "classify_gate",
+            "advance_gate",
+            "sign_off",
+            "submit_artifact",
+            "request_decision",
+            "record_decision",
+            "report_exception",
+            "circuit_breaker_trip",
+        ]),
+        gate: GateName.optional(),
+        details: z.record(z.string(), z.unknown()),
+    })),
+});
+// ─── recent_decisions ────────────────────────────────────────────────────────
+export const RecentDecisionsInput = z.object({
+    domain: DomainId.optional(),
+    /** ISO-8601 window start. */
+    since: z.string().optional(),
+    limit: z.number().int().positive().max(100).default(20),
+});
+export const RecentDecisionsOutput = z.object({
+    decisions: z.array(z.object({
+        adr_id: AdrId,
+        timestamp: z.string(),
+        question: z.string(),
+        chosen_option_id: z.string(),
+        signer: Signer,
+    })),
+});
+// ─── regenerate_manifest ─────────────────────────────────────────────────────
+export const RegenerateManifestInput = z.object({
+    domain: DomainId,
+    /** If true, write the regenerated AGENTS.yaml/AGENTS.md; if false, return diff only. */
+    apply: z.boolean().default(false),
+});
+export const RegenerateManifestOutput = z.object({
+    agents_yaml_path: z.string(),
+    agents_md_path: z.string(),
+    diff: z.string(),
+    applied: z.boolean(),
+});
+// ─── run_drift_audit ─────────────────────────────────────────────────────────
+export const RunDriftAuditInput = z.object({
+    domain: DomainId,
+});
+export const RunDriftAuditOutput = z.object({
+    orphan_skills: z.array(SkillName),
+    phantom_skills: z.array(SkillName),
+    yaml_skew: z.array(z.object({
+        skill: SkillName,
+        field: z.string(),
+        yaml_value: z.unknown(),
+        md_value: z.unknown(),
+    })),
+    unowned: z.array(SkillName),
+    missing_backlinks: z.array(z.object({
+        from: SkillName,
+        to: SkillName,
+    })),
+});
+// ════════════════════════════════════════════════════════════════════════════
+// PHASE 2 — DEV-DOMAIN SPECIFIC (stubbed initially)
+// ════════════════════════════════════════════════════════════════════════════
+export const RunTestsInput = z.object({
+    task_id: TaskId,
+    cwd: z.string().optional(),
+    filter: z.string().optional(),
+});
+export const RunTestsOutput = z.object({
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    duration_ms: z.number().int().nonnegative(),
+    failures: z.array(ExceptionItem).default([]),
+});
+export const ApplyDiffInput = z.object({
+    task_id: TaskId,
+    diff: z.string().min(1),
+    cwd: z.string().optional(),
+});
+export const ApplyDiffOutput = z.object({
+    files_changed: z.array(z.string()),
+});
+export const GitCommitInput = z.object({
+    task_id: TaskId,
+    message: z.string().min(1),
+    cwd: z.string().optional(),
+    paths: z.array(z.string()).default([]),
+});
+export const GitCommitOutput = z.object({
+    sha: z.string(),
+});
+export const CheckLintInput = z.object({
+    task_id: TaskId,
+    cwd: z.string().optional(),
+});
+export const CheckLintOutput = z.object({
+    clean: z.boolean(),
+    issues: z.array(ExceptionItem).default([]),
+});
+export const BuildInput = z.object({
+    task_id: TaskId,
+    cwd: z.string().optional(),
+});
+export const BuildOutput = z.object({
+    succeeded: z.boolean(),
+    errors: z.array(ExceptionItem).default([]),
+});
+export const DependencySupplyChainInput = z.object({
+    task_id: TaskId,
+    cwd: z.string().optional(),
+});
+export const DependencySupplyChainOutput = z.object({
+    vulnerabilities: z.array(ExceptionItem).default([]),
+    total_deps: z.number().int().nonnegative(),
+});
+export const DockerComposeInput = z.object({
+    task_id: TaskId,
+    command: z.enum(["up", "down", "ps", "logs"]),
+    cwd: z.string().optional(),
+});
+export const DockerComposeOutput = z.object({
+    exit_code: z.number().int(),
+    stdout: z.string(),
+    stderr: z.string(),
+});
+export const E2EPlaywrightInput = z.object({
+    task_id: TaskId,
+    spec: z.string().optional(),
+    cwd: z.string().optional(),
+});
+export const E2EPlaywrightOutput = z.object({
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    failures: z.array(ExceptionItem).default([]),
+});
+// ════════════════════════════════════════════════════════════════════════════
+// TOOL REGISTRY — name → { input, output } for runtime dispatch
+// ════════════════════════════════════════════════════════════════════════════
+export const TOOL_REGISTRY = {
+    // Phase 1
+    load_role: { input: LoadRoleInput, output: LoadRoleOutput },
+    list_skills: { input: ListSkillsInput, output: ListSkillsOutput },
+    get_skill: { input: GetSkillInput, output: GetSkillOutput },
+    request_decision: { input: RequestDecisionInput, output: RequestDecisionOutput },
+    record_decision: { input: RecordDecisionInput, output: RecordDecisionOutput },
+    classify_gate: { input: ClassifyGateInput, output: ClassifyGateOutput },
+    advance_gate: { input: AdvanceGateInput, output: AdvanceGateOutput },
+    current_gate: { input: CurrentGateInput, output: CurrentGateOutput },
+    sign_off: { input: SignOffInput, output: SignOffOutput },
+    submit_artifact: { input: SubmitArtifactInput, output: SubmitArtifactOutput },
+    verify_claim: { input: VerifyClaimInput, output: VerifyClaimOutput },
+    report_exception: { input: ReportExceptionInput, output: ReportExceptionOutput },
+    get_artifact: { input: GetArtifactInput, output: GetArtifactOutput },
+    list_artifacts: { input: ListArtifactsInput, output: ListArtifactsOutput },
+    audit_trail: { input: AuditTrailInput, output: AuditTrailOutput },
+    recent_decisions: { input: RecentDecisionsInput, output: RecentDecisionsOutput },
+    regenerate_manifest: { input: RegenerateManifestInput, output: RegenerateManifestOutput },
+    run_drift_audit: { input: RunDriftAuditInput, output: RunDriftAuditOutput },
+    // Phase 2
+    run_tests: { input: RunTestsInput, output: RunTestsOutput },
+    apply_diff: { input: ApplyDiffInput, output: ApplyDiffOutput },
+    git_commit: { input: GitCommitInput, output: GitCommitOutput },
+    check_lint: { input: CheckLintInput, output: CheckLintOutput },
+    build: { input: BuildInput, output: BuildOutput },
+    dependency_supply_chain: {
+        input: DependencySupplyChainInput,
+        output: DependencySupplyChainOutput,
+    },
+    docker_compose: { input: DockerComposeInput, output: DockerComposeOutput },
+    e2e_playwright: { input: E2EPlaywrightInput, output: E2EPlaywrightOutput },
+};

package/dist/shared/vocabulary.d.ts

@@ -0,0 +1,155 @@
+import { z } from "zod";
+/**
+ * Controlled vocabulary for the code-ai system.
+ *
+ * Every enum here is a closed set. Extensions go through
+ * `request_decision` → ADR → version bump of the shared types module (src/shared), then
+ * propagate atomically to both consumers (installer + mcp).
+ *
+ * Sourced from: docs/architecture-redesign/2026-05-23-context.md
+ *               (sections: STRUCTURED METADATA, ARTEFACTS AND LIMITS).
+ */
+/** Three pipeline shapes per domain. Full = all gates; Bugfix = compressed; Hotfix = single RG gate. */
+export declare const PipelineMode: z.ZodEnum<{
+    full: "full";
+    bugfix: "bugfix";
+    hotfix: "hotfix";
+}>;
+export type PipelineMode = z.infer<typeof PipelineMode>;
+/** Full development pipeline (8 gates). Other domains may use a subset; pipeline.yaml declares which. */
+export declare const GateName: z.ZodEnum<{
+    PM: "PM";
+    UX: "UX";
+    ARCH: "ARCH";
+    DEV: "DEV";
+    REV: "REV";
+    OPS: "OPS";
+    TEST: "TEST";
+    RG: "RG";
+}>;
+export type GateName = z.infer<typeof GateName>;
+/**
+ * LLM MUST classify each gate before producing artifact. Per the silent-by-default contract:
+ *   - auto_resolve: green path, no DEN attention required, artifact still produced for audit
+ *   - fork:        decision-point that needs DEN — surfaces via request_decision
+ *   - exception:   automated check failed, breakdown written to exception channel
+ */
+export declare const ClassificationOutcome: z.ZodEnum<{
+    auto_resolve: "auto_resolve";
+    fork: "fork";
+    exception: "exception";
+}>;
+export type ClassificationOutcome = z.infer<typeof ClassificationOutcome>;
+/** Every write goes through submit_artifact, which enforces the line cap declared here. */
+export declare const ArtifactClass: z.ZodEnum<{
+    skill: "skill";
+    adr: "adr";
+    persona: "persona";
+    role: "role";
+    diary: "diary";
+    working_report: "working_report";
+    handoff: "handoff";
+    memory_index: "memory_index";
+}>;
+export type ArtifactClass = z.infer<typeof ArtifactClass>;
+/** Hard caps from 2026-05-23-context.md § ARTIFACTS AND LIMITS. */
+export declare const ARTIFACT_LINE_CAP: Record<ArtifactClass, number | null>;
+/** Top-level domain that owns a pipeline. */
+export declare const DomainId: z.ZodEnum<{
+    development: "development";
+    content: "content";
+    analytics: "analytics";
+    product: "product";
+}>;
+export type DomainId = z.infer<typeof DomainId>;
+/**
+ * Per 2026-05-23-context.md § МЕТРИКИ SKILLS:
+ *   mandatory     → compliance in outputs, not invocation count
+ *   triggered     → trigger accuracy
+ *   reference     → recall on missed opportunities (MCP actively hints via PreToolUse)
+ *   discretionary → standard up/neutral/down rating
+ */
+export declare const SkillType: z.ZodEnum<{
+    mandatory: "mandatory";
+    triggered: "triggered";
+    reference: "reference";
+    discretionary: "discretionary";
+}>;
+export type SkillType = z.infer<typeof SkillType>;
+/** "den" = the user. "mcp" = auto-pass via deterministic check. "system" = circuit-breaker / audit. */
+export declare const Signer: z.ZodEnum<{
+    mcp: "mcp";
+    den: "den";
+    system: "system";
+}>;
+export type Signer = z.infer<typeof Signer>;
+/**
+ * tech + topic enums are seeded at migration start (<=30 each per plan).
+ * MCP refuses unknown values at submit_artifact time.
+ * Use z.string() with refine() in consumers when the curated list is loaded from disk;
+ * the seeds here are placeholders for compile-time safety on shipped skills.
+ */
+export declare const TechSeed: z.ZodEnum<{
+    typescript: "typescript";
+    node: "node";
+    react: "react";
+    python: "python";
+    go: "go";
+    rust: "rust";
+    monaco: "monaco";
+    vscode: "vscode";
+    mongodb: "mongodb";
+    postgres: "postgres";
+    docker: "docker";
+    playwright: "playwright";
+    vitest: "vitest";
+    general: "general";
+    a11y: "a11y";
+    css: "css";
+    express: "express";
+    n8n: "n8n";
+    rtk: "rtk";
+    tailwind: "tailwind";
+    tanstack: "tanstack";
+    wix: "wix";
+    bun: "bun";
+    biome: "biome";
+    k8s: "k8s";
+    zustand: "zustand";
+    stryker: "stryker";
+    mutmut: "mutmut";
+    "fast-check": "fast-check";
+    hypothesis: "hypothesis";
+    eslint: "eslint";
+    ruff: "ruff";
+    pytest: "pytest";
+    faker: "faker";
+    factory_boy: "factory_boy";
+    husky: "husky";
+    "pre-commit": "pre-commit";
+}>;
+export type TechSeed = z.infer<typeof TechSeed>;
+export declare const TopicSeed: z.ZodEnum<{
+    general: "general";
+    a11y: "a11y";
+    architecture: "architecture";
+    refactoring: "refactoring";
+    testing: "testing";
+    security: "security";
+    performance: "performance";
+    documentation: "documentation";
+    "design-patterns": "design-patterns";
+    "data-modelling": "data-modelling";
+    legacy: "legacy";
+    ux: "ux";
+    review: "review";
+    ops: "ops";
+    pm: "pm";
+    orchestration: "orchestration";
+    qa: "qa";
+    "design-systems": "design-systems";
+    observability: "observability";
+    compliance: "compliance";
+    release: "release";
+}>;
+export type TopicSeed = z.infer<typeof TopicSeed>;