forgium 0.1.0

package/dist/core/repository/repo-discovery.d.ts

@@ -0,0 +1 @@
+export declare function findRepositoryRoot(start?: string): Promise<string>;

package/dist/core/repository/repo-discovery.js

@@ -0,0 +1,17 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ForgiumRepositoryNotFoundError } from "../errors/forgium-errors.js";
+export async function findRepositoryRoot(start = process.cwd()) {
+    let current = path.resolve(start);
+    while (true) {
+        try {
+            if ((await fs.stat(path.join(current, ".git"))).isDirectory())
+                return current;
+        }
+        catch { }
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new ForgiumRepositoryNotFoundError();
+        current = parent;
+    }
+}

package/dist/core/schemas/draft.schema.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const DraftSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    created: z.ZodString;
+    source: z.ZodObject<{
+        type: z.ZodString;
+        ref: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        ref: string;
+    }, {
+        type: string;
+        ref: string;
+    }>;
+    title: z.ZodString;
+    goal: z.ZodString;
+    acceptance: z.ZodArray<z.ZodString, "many">;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    source: {
+        type: string;
+        ref: string;
+    };
+    title: string;
+    goal: string;
+    acceptance: string[];
+    constraints?: string[] | undefined;
+}, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    source: {
+        type: string;
+        ref: string;
+    };
+    title: string;
+    goal: string;
+    acceptance: string[];
+    constraints?: string[] | undefined;
+}>;

package/dist/core/schemas/draft.schema.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const DraftSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1).regex(/^draft-[a-z0-9][a-z0-9-]*$/),
+    created: z.string().datetime({ offset: true }),
+    source: z.object({ type: z.string().min(1), ref: z.string().min(1) }),
+    title: z.string().min(1),
+    goal: z.string(),
+    acceptance: z.array(z.string()),
+    constraints: z.array(z.string()).optional()
+});

package/dist/core/schemas/inbox.schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const InboxFrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodString;
+    created: z.ZodString;
+    status: z.ZodEnum<["captured", "drafted", "promoted", "merged", "deferred"]>;
+    draftRef: z.ZodOptional<z.ZodString>;
+    featureRef: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "captured" | "drafted" | "promoted" | "merged" | "deferred";
+    id: string;
+    created: string;
+    source: string;
+    draftRef?: string | undefined;
+    featureRef?: string | undefined;
+}, {
+    status: "captured" | "drafted" | "promoted" | "merged" | "deferred";
+    id: string;
+    created: string;
+    source: string;
+    draftRef?: string | undefined;
+    featureRef?: string | undefined;
+}>;

package/dist/core/schemas/inbox.schema.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const InboxFrontmatterSchema = z.object({
+    id: z.string().min(1).regex(/^inbox-[A-Za-z0-9T:+-]+-[a-z0-9]+$/),
+    source: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/),
+    created: z.string().datetime({ offset: true }),
+    status: z.enum(["captured", "drafted", "promoted", "merged", "deferred"]),
+    draftRef: z.string().optional(),
+    featureRef: z.string().optional()
+});

package/dist/core/schemas/manifest.schema.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+export declare const ManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    title: z.ZodString;
+    created: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        ref: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        ref: string;
+    }, {
+        type: string;
+        ref: string;
+    }>>;
+    goal: z.ZodString;
+    acceptance: z.ZodArray<z.ZodString, "many">;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    verification: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            run: z.ZodString;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            run: string;
+            timeoutMs?: number | undefined;
+        }, {
+            name: string;
+            run: string;
+            timeoutMs?: number | undefined;
+        }>, "many">;
+        requiredEvidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            criterion: z.ZodString;
+            kind: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            criterion: string;
+            kind: string;
+        }, {
+            criterion: string;
+            kind: string;
+        }>, "many">>;
+        review: z.ZodOptional<z.ZodLiteral<"required">>;
+    }, "strip", z.ZodTypeAny, {
+        commands: {
+            name: string;
+            run: string;
+            timeoutMs?: number | undefined;
+        }[];
+        review?: "required" | undefined;
+        requiredEvidence?: {
+            criterion: string;
+            kind: string;
+        }[] | undefined;
+    }, {
+        commands: {
+            name: string;
+            run: string;
+            timeoutMs?: number | undefined;
+        }[];
+        review?: "required" | undefined;
+        requiredEvidence?: {
+            criterion: string;
+            kind: string;
+        }[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    title: string;
+    goal: string;
+    acceptance: string[];
+    verification?: {
+        commands: {
+            name: string;
+            run: string;
+            timeoutMs?: number | undefined;
+        }[];
+        review?: "required" | undefined;
+        requiredEvidence?: {
+            criterion: string;
+            kind: string;
+        }[] | undefined;
+    } | undefined;
+    source?: {
+        type: string;
+        ref: string;
+    } | undefined;
+    constraints?: string[] | undefined;
+}, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    title: string;
+    goal: string;
+    acceptance: string[];
+    verification?: {
+        commands: {
+            name: string;
+            run: string;
+            timeoutMs?: number | undefined;
+        }[];
+        review?: "required" | undefined;
+        requiredEvidence?: {
+            criterion: string;
+            kind: string;
+        }[] | undefined;
+    } | undefined;
+    source?: {
+        type: string;
+        ref: string;
+    } | undefined;
+    constraints?: string[] | undefined;
+}>;

package/dist/core/schemas/manifest.schema.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const ManifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1).regex(/^feature-[a-z0-9][a-z0-9-]*$/),
+    title: z.string().min(1),
+    created: z.string().datetime({ offset: true }),
+    source: z.object({ type: z.string().min(1), ref: z.string().min(1) }).optional(),
+    goal: z.string().min(1),
+    acceptance: z.array(z.string().min(1)).min(1),
+    constraints: z.array(z.string().min(1)).optional(),
+    verification: z.object({
+        commands: z.array(z.object({
+            name: z.string().min(1),
+            run: z.string().min(1),
+            timeoutMs: z.number().int().positive().optional()
+        })),
+        requiredEvidence: z.array(z.object({ criterion: z.string().min(1), kind: z.string().min(1) })).optional(),
+        review: z.literal("required").optional()
+    }).optional()
+});

package/dist/core/schemas/receipt.schema.d.ts

@@ -0,0 +1,355 @@
+import { z } from "zod";
+export declare const ReceiptSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    created: z.ZodString;
+    feature: z.ZodObject<{
+        id: z.ZodString;
+        manifestPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        manifestPath: string;
+    }, {
+        id: string;
+        manifestPath: string;
+    }>;
+    runId: z.ZodString;
+    actor: z.ZodObject<{
+        type: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }>;
+    outcome: z.ZodString;
+    summary: z.ZodString;
+} & {
+    kind: z.ZodLiteral<"execution">;
+    engine: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "execution";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: string;
+    summary: string;
+    engine?: string | undefined;
+    artifacts?: string[] | undefined;
+}, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "execution";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: string;
+    summary: string;
+    engine?: string | undefined;
+    artifacts?: string[] | undefined;
+}>, z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    created: z.ZodString;
+    feature: z.ZodObject<{
+        id: z.ZodString;
+        manifestPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        manifestPath: string;
+    }, {
+        id: string;
+        manifestPath: string;
+    }>;
+    runId: z.ZodString;
+    actor: z.ZodObject<{
+        type: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }>;
+    summary: z.ZodString;
+} & {
+    kind: z.ZodLiteral<"verification">;
+    outcome: z.ZodEnum<["passed", "failed", "manual_required", "not_configured", "cancelled"]>;
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        cwd: z.ZodString;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNumber;
+        status: z.ZodEnum<["passed", "failed", "cancelled"]>;
+        outputSummary: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        status: "passed" | "failed" | "cancelled";
+        name: string;
+        command: string;
+        cwd: string;
+        exitCode: number | null;
+        durationMs: number;
+        outputSummary: string;
+    }, {
+        status: "passed" | "failed" | "cancelled";
+        name: string;
+        command: string;
+        cwd: string;
+        exitCode: number | null;
+        durationMs: number;
+        outputSummary: string;
+    }>, "many">;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        criterion: z.ZodString;
+        kind: z.ZodString;
+        status: z.ZodEnum<["passed", "failed", "pending"]>;
+        ref: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "passed" | "failed" | "pending";
+        criterion: string;
+        kind: string;
+        ref?: string | undefined;
+    }, {
+        status: "passed" | "failed" | "pending";
+        criterion: string;
+        kind: string;
+        ref?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "verification";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: "passed" | "failed" | "manual_required" | "not_configured" | "cancelled";
+    summary: string;
+    checks: {
+        status: "passed" | "failed" | "cancelled";
+        name: string;
+        command: string;
+        cwd: string;
+        exitCode: number | null;
+        durationMs: number;
+        outputSummary: string;
+    }[];
+    evidence?: {
+        status: "passed" | "failed" | "pending";
+        criterion: string;
+        kind: string;
+        ref?: string | undefined;
+    }[] | undefined;
+}, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "verification";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: "passed" | "failed" | "manual_required" | "not_configured" | "cancelled";
+    summary: string;
+    checks: {
+        status: "passed" | "failed" | "cancelled";
+        name: string;
+        command: string;
+        cwd: string;
+        exitCode: number | null;
+        durationMs: number;
+        outputSummary: string;
+    }[];
+    evidence?: {
+        status: "passed" | "failed" | "pending";
+        criterion: string;
+        kind: string;
+        ref?: string | undefined;
+    }[] | undefined;
+}>, z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    created: z.ZodString;
+    feature: z.ZodObject<{
+        id: z.ZodString;
+        manifestPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        manifestPath: string;
+    }, {
+        id: string;
+        manifestPath: string;
+    }>;
+    runId: z.ZodString;
+    actor: z.ZodObject<{
+        type: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }>;
+    summary: z.ZodString;
+} & {
+    kind: z.ZodLiteral<"review">;
+    outcome: z.ZodEnum<["approved", "changes_requested", "blocked"]>;
+    decision: z.ZodEnum<["approved", "changes_requested", "blocked"]>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "review";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: "blocked" | "approved" | "changes_requested";
+    summary: string;
+    decision: "blocked" | "approved" | "changes_requested";
+    findings?: string[] | undefined;
+}, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "review";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: "blocked" | "approved" | "changes_requested";
+    summary: string;
+    decision: "blocked" | "approved" | "changes_requested";
+    findings?: string[] | undefined;
+}>, z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    created: z.ZodString;
+    feature: z.ZodObject<{
+        id: z.ZodString;
+        manifestPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        manifestPath: string;
+    }, {
+        id: string;
+        manifestPath: string;
+    }>;
+    runId: z.ZodString;
+    actor: z.ZodObject<{
+        type: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }, {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    }>;
+    summary: z.ZodString;
+} & {
+    kind: z.ZodLiteral<"handoff">;
+    outcome: z.ZodEnum<["failed", "blocked", "needs_human", "cancelled"]>;
+    reason: z.ZodString;
+    relatedReceipt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "handoff";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: "blocked" | "failed" | "cancelled" | "needs_human";
+    summary: string;
+    reason: string;
+    relatedReceipt?: string | undefined;
+}, {
+    schemaVersion: 1;
+    id: string;
+    created: string;
+    kind: "handoff";
+    feature: {
+        id: string;
+        manifestPath: string;
+    };
+    runId: string;
+    actor: {
+        type: string;
+        name: string;
+        version?: string | undefined;
+    };
+    outcome: "blocked" | "failed" | "cancelled" | "needs_human";
+    summary: string;
+    reason: string;
+    relatedReceipt?: string | undefined;
+}>]>;

package/dist/core/schemas/receipt.schema.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+const ReceiptBaseSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1).regex(/^receipt-[A-Za-z0-9T:+-]+-[a-z0-9]+-[a-z-]+$/),
+    kind: z.enum(["execution", "verification", "review", "handoff"]),
+    created: z.string().datetime({ offset: true }),
+    feature: z.object({ id: z.string().min(1), manifestPath: z.string().min(1) }),
+    runId: z.string().min(1),
+    actor: z.object({ type: z.string().min(1), name: z.string().min(1), version: z.string().optional() }),
+    outcome: z.string().min(1),
+    summary: z.string().min(1)
+});
+const VerificationReceiptSchema = ReceiptBaseSchema.extend({
+    kind: z.literal("verification"),
+    outcome: z.enum(["passed", "failed", "manual_required", "not_configured", "cancelled"]),
+    checks: z.array(z.object({
+        name: z.string().min(1),
+        command: z.string().min(1),
+        cwd: z.string().min(1),
+        exitCode: z.number().int().nullable(),
+        durationMs: z.number().nonnegative(),
+        status: z.enum(["passed", "failed", "cancelled"]),
+        outputSummary: z.string()
+    })),
+    evidence: z.array(z.object({
+        criterion: z.string().min(1),
+        kind: z.string().min(1),
+        status: z.enum(["passed", "failed", "pending"]),
+        ref: z.string().optional()
+    })).optional()
+});
+const ReviewReceiptSchema = ReceiptBaseSchema.extend({
+    kind: z.literal("review"),
+    outcome: z.enum(["approved", "changes_requested", "blocked"]),
+    decision: z.enum(["approved", "changes_requested", "blocked"]),
+    findings: z.array(z.string().min(1)).optional()
+});
+const HandoffReceiptSchema = ReceiptBaseSchema.extend({
+    kind: z.literal("handoff"),
+    outcome: z.enum(["failed", "blocked", "needs_human", "cancelled"]),
+    reason: z.string().min(1),
+    relatedReceipt: z.string().optional()
+});
+const ExecutionReceiptSchema = ReceiptBaseSchema.extend({
+    kind: z.literal("execution"),
+    engine: z.string().optional(),
+    artifacts: z.array(z.string().min(1)).optional()
+});
+export const ReceiptSchema = z.discriminatedUnion("kind", [
+    ExecutionReceiptSchema,
+    VerificationReceiptSchema,
+    ReviewReceiptSchema,
+    HandoffReceiptSchema
+]);

package/dist/core/services/id.d.ts

@@ -0,0 +1,4 @@
+export declare function slugify(value: string): string;
+export declare function shortId(bytes?: number): string;
+export declare function timestampForFile(date?: Date): string;
+export declare function isoNow(): string;

package/dist/core/services/id.js

@@ -0,0 +1,9 @@
+import crypto from "node:crypto";
+export function slugify(value) {
+    return value.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "feature";
+}
+export function shortId(bytes = 2) { return crypto.randomBytes(bytes).toString("hex"); }
+export function timestampForFile(date = new Date()) {
+    return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+export function isoNow() { return new Date().toISOString(); }

package/dist/core/services/spec-flow-commands.d.ts

@@ -0,0 +1,6 @@
+export interface SpecFlowCommandHints {
+    init: string;
+    implement: string;
+    next: string;
+}
+export declare function specFlowCommandsForSpec(specPath: string): SpecFlowCommandHints;

package/dist/core/services/spec-flow-commands.js

@@ -0,0 +1,7 @@
+export function specFlowCommandsForSpec(specPath) {
+    return {
+        init: `/spec-flow-init ${specPath}`,
+        implement: `/spec-flow-implement ${specPath}`,
+        next: `/spec-flow-next ${specPath}`
+    };
+}

package/dist/core/transitions/transition-rules.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureState } from "../domain/types.js";
+export declare const allowedTransitions: Record<FeatureState, FeatureState[]>;
+export declare function canTransition(from: FeatureState, to: FeatureState): boolean;