code-ai-installer 3.0.0 → 4.0.0

package/dist/shared/frontmatter.d.ts

@@ -0,0 +1,150 @@
+import { z } from "zod";
+/**
+ * Skill frontmatter — the structural anti-drift contract.
+ *
+ * MCP's `submit_artifact(class="skill", ...)` validates against this schema and
+ * refuses:
+ *   - missing `owners` (orphan skills are no longer possible)
+ *   - unknown values in `tech` / `topic` (controlled vocabulary)
+ *   - `related` without bidirectional backlink in the referenced skill
+ *
+ * From: 2026-05-23-context.md § STRUCTURED METADATA.
+ */
+/** Agent role-name referenced by `owners[]`. Must match an agent.md in the same domain. */
+export declare const AgentName: z.ZodString;
+export type AgentName = z.infer<typeof AgentName>;
+/** Skill identifier — kebab-case, must match the directory name on disk. */
+export declare const SkillName: z.ZodString;
+export type SkillName = z.infer<typeof SkillName>;
+/**
+ * SkillFrontmatter — the source of truth for a skill's metadata.
+ *
+ * Mirrored at write-time into AGENTS.yaml's `skills:` block by
+ * `regenerate_manifest(domain)`. Direct YAML edits to AGENTS.yaml are blocked
+ * at PreToolUse — the only path is editing the skill's frontmatter then
+ * regenerating.
+ */
+export declare const SkillFrontmatter: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    type: z.ZodEnum<{
+        mandatory: "mandatory";
+        triggered: "triggered";
+        reference: "reference";
+        discretionary: "discretionary";
+    }>;
+    domain: z.ZodEnum<{
+        development: "development";
+        content: "content";
+        analytics: "analytics";
+        product: "product";
+    }>;
+    owners: z.ZodArray<z.ZodString>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        PM: "PM";
+        UX: "UX";
+        ARCH: "ARCH";
+        DEV: "DEV";
+        REV: "REV";
+        OPS: "OPS";
+        TEST: "TEST";
+        RG: "RG";
+    }>>>;
+    tech: z.ZodDefault<z.ZodArray<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";
+    }>>>;
+    topic: z.ZodDefault<z.ZodArray<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";
+    }>>>;
+    triggers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    related: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    budget_lines: z.ZodDefault<z.ZodNumber>;
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    license: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString]>>;
+}, z.core.$strip>;
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatter>;
+/**
+ * Role frontmatter — agent.md header. Defines the role's tool allowlist (referenced by name;
+ * MCP resolves to concrete tool set) and which gates the role can sign off on.
+ */
+export declare const RoleFrontmatter: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    domain: z.ZodEnum<{
+        development: "development";
+        content: "content";
+        analytics: "analytics";
+        product: "product";
+    }>;
+    signs_off_at: z.ZodArray<z.ZodEnum<{
+        PM: "PM";
+        UX: "UX";
+        ARCH: "ARCH";
+        DEV: "DEV";
+        REV: "REV";
+        OPS: "OPS";
+        TEST: "TEST";
+        RG: "RG";
+    }>>;
+    tool_allowlist: z.ZodString;
+    budget_lines: z.ZodDefault<z.ZodNumber>;
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+}, z.core.$strip>;
+export type RoleFrontmatter = z.infer<typeof RoleFrontmatter>;

package/dist/shared/frontmatter.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { DomainId, GateName, SkillType, TechSeed, TopicSeed, } from "./vocabulary.js";
+/**
+ * Skill frontmatter — the structural anti-drift contract.
+ *
+ * MCP's `submit_artifact(class="skill", ...)` validates against this schema and
+ * refuses:
+ *   - missing `owners` (orphan skills are no longer possible)
+ *   - unknown values in `tech` / `topic` (controlled vocabulary)
+ *   - `related` without bidirectional backlink in the referenced skill
+ *
+ * From: 2026-05-23-context.md § STRUCTURED METADATA.
+ */
+/** Agent role-name referenced by `owners[]`. Must match an agent.md in the same domain. */
+export const AgentName = z.string().min(1).regex(/^[a-z][a-z0-9_]*$/, {
+    message: "agent name must be snake_case",
+});
+/** Skill identifier — kebab-case, must match the directory name on disk. */
+export const SkillName = z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, {
+    message: "skill name must be kebab-case",
+});
+/**
+ * SkillFrontmatter — the source of truth for a skill's metadata.
+ *
+ * Mirrored at write-time into AGENTS.yaml's `skills:` block by
+ * `regenerate_manifest(domain)`. Direct YAML edits to AGENTS.yaml are blocked
+ * at PreToolUse — the only path is editing the skill's frontmatter then
+ * regenerating.
+ */
+export const SkillFrontmatter = z.object({
+    name: SkillName,
+    description: z.string().min(1).max(1000),
+    type: SkillType,
+    domain: DomainId,
+    /** Agent roles that own this skill (consume + maintain it). Empty array is a structural error. */
+    owners: z.array(AgentName).min(1),
+    /** Gates at which this skill applies. Empty = applies anywhere in the domain. */
+    gates: z.array(GateName).default([]),
+    /** Tech stack tags from the controlled vocab. Use TechSeed values; consumers may broaden via z.string() refine. */
+    tech: z.array(TechSeed).default([]),
+    /** Topic tags from the controlled vocab. */
+    topic: z.array(TopicSeed).default([]),
+    /**
+     * Machine-scannable trigger phrases. Used by:
+     *   - reference skills: PreToolUse hook checks context for match, hints "this skill is available"
+     *   - triggered skills: MCP scores trigger_accuracy from invocations
+     */
+    triggers: z.array(z.string().min(1)).default([]),
+    /** Bidirectional backlinks. MCP enforces the reverse edge at write time. */
+    related: z.array(SkillName).default([]),
+    /** Body line budget. Default 300 (workflow skills); type=reference may extend up to 700
+     *  to support growing canonical libraries (ADR-DEV-010, ADR-DEV-015 raised to 500,
+     *  ADR-DEV-022 raised to 700 for composite vendor-stack references like
+     *  n8n-pinecone-qdrant-supabase-reference). Workflows may use tactical per-skill raises
+     *  up to 400 (precedent ADR-DEV-021 raised k8s-manifests-conventions workflow to 350).
+     *  Raised to 800 in ADR-DEV-034 for state-zustand-beast-practices-reference (750)
+     *  — densest examples skill in codebase, DEN-locked rule prevents trim. */
+    budget_lines: z.number().int().positive().max(800).default(300),
+    /** Frontmatter version. Bumped when SkillFrontmatter shape changes. */
+    schema_version: z.literal(1).default(1),
+    /** Optional provenance preserved from pre-migration frontmatter (license/source). */
+    license: z.string().optional(),
+    source: z.string().url().or(z.string().min(1)).optional(),
+});
+/**
+ * Role frontmatter — agent.md header. Defines the role's tool allowlist (referenced by name;
+ * MCP resolves to concrete tool set) and which gates the role can sign off on.
+ */
+export const RoleFrontmatter = z.object({
+    name: AgentName,
+    description: z.string().min(1).max(1000),
+    domain: DomainId,
+    /** Gates where this role is authorized to sign off. */
+    signs_off_at: z.array(GateName).min(1),
+    /** Named tool-allowlist policy. MCP looks up the concrete tool list by name. */
+    tool_allowlist: z.string().min(1),
+    budget_lines: z.number().int().positive().max(250).default(250),
+    schema_version: z.literal(1).default(1),
+});

package/dist/shared/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared TypeScript types + zod schemas for the code-ai-installer package.
+ *
+ * Consumed by:
+ *   - code-ai-installer CLI (frontmatter validation, manifest regeneration)
+ *   - code-ai-mcp runtime (pipeline state machine, tool I/O contracts)
+ *
+ * Pre-DEV-100 this lived as a separate `@denish1209/types` npm package;
+ * DEV-100 consolidated it into `code-ai-installer/src/shared/`. The legacy
+ * `@denish1209/types@0.1.0` is deprecated on npm.
+ *
+ * See ../../../docs/architecture-redesign/ for the source-of-truth specs:
+ *   - persona-base.md / persona-architecture.md
+ *   - 2026-05-23-context.md (paradigm shift, principles, artifact caps)
+ *   - dev-domain-planning-kickoff.md (pipeline.yaml scope)
+ */
+export declare const VERSION = "0.0.0";
+export * from "./vocabulary.js";
+export * from "./frontmatter.js";
+export * from "./persona.js";
+export * from "./pipeline.js";
+export * from "./tools.js";

package/dist/shared/index.js

@@ -0,0 +1,22 @@
+/**
+ * Shared TypeScript types + zod schemas for the code-ai-installer package.
+ *
+ * Consumed by:
+ *   - code-ai-installer CLI (frontmatter validation, manifest regeneration)
+ *   - code-ai-mcp runtime (pipeline state machine, tool I/O contracts)
+ *
+ * Pre-DEV-100 this lived as a separate `@denish1209/types` npm package;
+ * DEV-100 consolidated it into `code-ai-installer/src/shared/`. The legacy
+ * `@denish1209/types@0.1.0` is deprecated on npm.
+ *
+ * See ../../../docs/architecture-redesign/ for the source-of-truth specs:
+ *   - persona-base.md / persona-architecture.md
+ *   - 2026-05-23-context.md (paradigm shift, principles, artifact caps)
+ *   - dev-domain-planning-kickoff.md (pipeline.yaml scope)
+ */
+export const VERSION = "0.0.0";
+export * from "./vocabulary.js";
+export * from "./frontmatter.js";
+export * from "./persona.js";
+export * from "./pipeline.js";
+export * from "./tools.js";

package/dist/shared/persona.d.ts

@@ -0,0 +1,248 @@
+import { z } from "zod";
+/**
+ * Persona schema — two layers + merge result.
+ *
+ * Per docs/architecture-redesign/persona-architecture.md:
+ *   - persona-base.md ships universal principles (loaded by every install)
+ *   - persona-user-{handle}.md is local-only (gitignored, frontmatter flag, files-whitelist excluded)
+ *   - the merged persona is what `load_role` returns to SessionStart
+ *
+ * Provenance per property is mandatory (DEN: "must be visible where each rule came from").
+ */
+/**
+ * Provenance pointer — where a persona property was derived from.
+ * One of: a diary timestamp, an ADR id, a conversation reference, or a MemPalace drawer id.
+ */
+export declare const Provenance: z.ZodObject<{
+    source: z.ZodEnum<{
+        adr: "adr";
+        diary: "diary";
+        conversation: "conversation";
+        drawer: "drawer";
+        manual: "manual";
+    }>;
+    ref: z.ZodString;
+    date: z.ZodString;
+}, z.core.$strip>;
+export type Provenance = z.infer<typeof Provenance>;
+/** A single persona property with its provenance chain. */
+export declare const PersonaProperty: z.ZodObject<{
+    value: z.ZodString;
+    provenance: z.ZodArray<z.ZodObject<{
+        source: z.ZodEnum<{
+            adr: "adr";
+            diary: "diary";
+            conversation: "conversation";
+            drawer: "drawer";
+            manual: "manual";
+        }>;
+        ref: z.ZodString;
+        date: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PersonaProperty = z.infer<typeof PersonaProperty>;
+/**
+ * The four kinds of persona content (NOT a character archetype):
+ *   epistemic_stance — how I form/hold beliefs
+ *   defaults         — my default behavior under ambiguity
+ *   values           — what I optimize for
+ *   style            — communication style
+ */
+export declare const PersonaSection: z.ZodEnum<{
+    values: "values";
+    style: "style";
+    epistemic_stance: "epistemic_stance";
+    defaults: "defaults";
+}>;
+export type PersonaSection = z.infer<typeof PersonaSection>;
+/** Base persona — ships universal principles. Hard cap 200 lines (enforced at submit time, not in zod). */
+export declare const PersonaBase: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    layer: z.ZodLiteral<"base">;
+    epistemic_stance: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    defaults: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    values: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    style: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PersonaBase = z.infer<typeof PersonaBase>;
+/**
+ * User-layer persona — overrides + additions specific to one user.
+ * Same shape as base but with `local_only: true` flag that prevents shipping.
+ */
+export declare const PersonaUserLayer: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    layer: z.ZodLiteral<"user">;
+    user_handle: z.ZodString;
+    local_only: z.ZodLiteral<true>;
+    epistemic_stance: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    defaults: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    values: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    style: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PersonaUserLayer = z.infer<typeof PersonaUserLayer>;
+/** Merge result returned by load_role. User-layer properties append to (never replace) base properties. */
+export declare const PersonaMerged: z.ZodObject<{
+    base_version: z.ZodString;
+    user_handle: z.ZodNullable<z.ZodString>;
+    epistemic_stance: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    defaults: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    values: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    style: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                adr: "adr";
+                diary: "diary";
+                conversation: "conversation";
+                drawer: "drawer";
+                manual: "manual";
+            }>;
+            ref: z.ZodString;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PersonaMerged = z.infer<typeof PersonaMerged>;

package/dist/shared/persona.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+/**
+ * Persona schema — two layers + merge result.
+ *
+ * Per docs/architecture-redesign/persona-architecture.md:
+ *   - persona-base.md ships universal principles (loaded by every install)
+ *   - persona-user-{handle}.md is local-only (gitignored, frontmatter flag, files-whitelist excluded)
+ *   - the merged persona is what `load_role` returns to SessionStart
+ *
+ * Provenance per property is mandatory (DEN: "must be visible where each rule came from").
+ */
+/**
+ * Provenance pointer — where a persona property was derived from.
+ * One of: a diary timestamp, an ADR id, a conversation reference, or a MemPalace drawer id.
+ */
+export const Provenance = z.object({
+    source: z.enum(["diary", "adr", "conversation", "drawer", "manual"]),
+    ref: z.string().min(1),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+});
+/** A single persona property with its provenance chain. */
+export const PersonaProperty = z.object({
+    value: z.string().min(1),
+    provenance: z.array(Provenance).min(1),
+});
+/**
+ * The four kinds of persona content (NOT a character archetype):
+ *   epistemic_stance — how I form/hold beliefs
+ *   defaults         — my default behavior under ambiguity
+ *   values           — what I optimize for
+ *   style            — communication style
+ */
+export const PersonaSection = z.enum([
+    "epistemic_stance",
+    "defaults",
+    "values",
+    "style",
+]);
+/** Base persona — ships universal principles. Hard cap 200 lines (enforced at submit time, not in zod). */
+export const PersonaBase = z.object({
+    schema_version: z.literal(1).default(1),
+    layer: z.literal("base"),
+    epistemic_stance: z.array(PersonaProperty).default([]),
+    defaults: z.array(PersonaProperty).default([]),
+    values: z.array(PersonaProperty).default([]),
+    style: z.array(PersonaProperty).default([]),
+});
+/**
+ * User-layer persona — overrides + additions specific to one user.
+ * Same shape as base but with `local_only: true` flag that prevents shipping.
+ */
+export const PersonaUserLayer = z.object({
+    schema_version: z.literal(1).default(1),
+    layer: z.literal("user"),
+    user_handle: z.string().min(1),
+    /** Hard-required true; structural defense against the file ending up in installer ships-data. */
+    local_only: z.literal(true),
+    epistemic_stance: z.array(PersonaProperty).default([]),
+    defaults: z.array(PersonaProperty).default([]),
+    values: z.array(PersonaProperty).default([]),
+    style: z.array(PersonaProperty).default([]),
+});
+/** Merge result returned by load_role. User-layer properties append to (never replace) base properties. */
+export const PersonaMerged = z.object({
+    base_version: z.string().min(1),
+    user_handle: z.string().nullable(),
+    epistemic_stance: z.array(PersonaProperty),
+    defaults: z.array(PersonaProperty),
+    values: z.array(PersonaProperty),
+    style: z.array(PersonaProperty),
+});