@deftai/directive-core 0.91.0 → 0.93.0

package/dist/xbrief/paths.js

@@ -0,0 +1,123 @@
+/**
+ * Portable path expand + project-root containment for xbrief:create/verify (#3057).
+ *
+ * Uses real path APIs (node:path / node:os) — no slash-only logic.
+ * Default containment under project root fails closed on escape.
+ */
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, resolveContainedTarget, } from "../fs/contained-write.js";
+export class XbriefPathError extends Error {
+    code;
+    constructor(message, code = "XBRIEF_PATH_ERROR") {
+        super(message);
+        this.name = "XbriefPathError";
+        this.code = code;
+    }
+}
+/**
+ * Expand simple user path forms portably:
+ * - `~` / `~/…` / `~\…` → home directory
+ * - `%VAR%` (Windows-class env expansion) when present in the string
+ *
+ * Relative paths are left relative (caller resolves against project root or cwd).
+ */
+export function expandUserPath(input, options = {}) {
+    if (input.length === 0) {
+        throw new XbriefPathError("empty path", "XBRIEF_PATH_EMPTY");
+    }
+    const home = options.home ?? homedir();
+    const env = options.env ?? process.env;
+    let expanded = input.replace(/%([^%]+)%/g, (match, name) => {
+        const value = env[name];
+        return value !== undefined && value.length > 0 ? value : match;
+    });
+    if (expanded === "~") {
+        expanded = home;
+    }
+    else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+        expanded = join(home, expanded.slice(2));
+    }
+    // Env expansion may inject foreign separators (e.g. %USERPROFILE%\foo on Linux CI).
+    // Re-normalize with path.normalize after collapsing to platform-native separators.
+    const collapsed = expanded.replace(/\\/g, "/");
+    return normalize(collapsed);
+}
+/** Strip known xBRIEF suffixes to recover a write stem. */
+export function stripXbriefSuffix(pathLike) {
+    const lower = pathLike.toLowerCase();
+    if (lower.endsWith(".xbrief.json")) {
+        return pathLike.slice(0, -".xbrief.json".length);
+    }
+    if (lower.endsWith(".xbrief.md")) {
+        return pathLike.slice(0, -".xbrief.md".length);
+    }
+    return pathLike;
+}
+/**
+ * Resolve `--out` under `projectRoot` with user-path expansion and fail-closed
+ * containment. Returns absolute stem + format-specific artifact paths.
+ */
+export function resolveXbriefOutPaths(input) {
+    const projectRoot = resolve(input.projectRoot);
+    const expanded = expandUserPath(input.out, { home: input.home, env: input.env });
+    // Absolute (post-expand) paths must still nest under projectRoot.
+    // Relative paths resolve against projectRoot (not bare cwd) so containment is stable.
+    let candidate;
+    if (isAbsolute(expanded)) {
+        candidate = resolve(expanded);
+    }
+    else {
+        // When out is explicitly cwd-relative (./…), resolve against cwd then re-check root.
+        const cwd = input.cwd ?? process.cwd();
+        if (expanded === "." ||
+            expanded.startsWith(`.${sep}`) ||
+            expanded.startsWith("./") ||
+            expanded.startsWith(".\\")) {
+            candidate = resolve(cwd, expanded);
+        }
+        else {
+            candidate = resolve(projectRoot, expanded);
+        }
+    }
+    const stemRaw = stripXbriefSuffix(candidate);
+    let stemAbs;
+    try {
+        // resolveContainedTarget requires nested path (not the root itself).
+        // If stem equals root, fail with a clear message.
+        const rel = relative(projectRoot, stemAbsPlaceholder(projectRoot, stemRaw));
+        if (rel.length === 0) {
+            throw new XbriefPathError(`xbrief path refused: --out resolves to project root (need a file stem under the root)`, "XBRIEF_PATH_ESCAPE");
+        }
+        stemAbs = resolveContainedTarget(projectRoot, isAbsolute(stemRaw) ? stemRaw : relative(projectRoot, stemRaw));
+    }
+    catch (err) {
+        if (err instanceof XbriefPathError)
+            throw err;
+        if (err instanceof ContainedWriteError) {
+            throw new XbriefPathError(`xbrief path refused: --out escapes project root (${err.target})`, err.code === ContainedWriteErrorCode.ESCAPE ? "XBRIEF_PATH_ESCAPE" : err.code);
+        }
+        throw err;
+    }
+    const jsonAbs = input.format === "md" ? null : `${stemAbs}.xbrief.json`;
+    const mdAbs = input.format === "json" ? null : `${stemAbs}.xbrief.md`;
+    // Re-validate artifact paths under root (stem + suffix must stay nested).
+    for (const p of [jsonAbs, mdAbs]) {
+        if (p === null)
+            continue;
+        try {
+            resolveContainedTarget(projectRoot, p);
+        }
+        catch (err) {
+            if (err instanceof ContainedWriteError) {
+                throw new XbriefPathError(`xbrief path refused: artifact escapes project root (${p})`, "XBRIEF_PATH_ESCAPE");
+            }
+            throw err;
+        }
+    }
+    return { projectRoot, stemAbs, jsonAbs, mdAbs };
+}
+function stemAbsPlaceholder(projectRoot, stemRaw) {
+    return isAbsolute(stemRaw) ? resolve(stemRaw) : resolve(projectRoot, stemRaw);
+}
+//# sourceMappingURL=paths.js.map

package/dist/xbrief/styles.d.ts

@@ -0,0 +1,36 @@
+/**
+ * P0 xBRIEF style templates and markdown section maps (#3057).
+ *
+ * One schema spine (xBRIEF v0.8); markdown is a dense render of the same plan,
+ * not a second dialect.
+ */
+import type { XbriefDocument, XbriefStyle } from "./types.js";
+/** Required H2 section titles in the markdown form per style. */
+export declare const MD_REQUIRED_SECTIONS: Readonly<Record<XbriefStyle, readonly string[]>>;
+export interface BuildDocumentInput {
+    style: XbriefStyle;
+    title: string;
+    id?: string;
+    status?: string;
+    description?: string;
+    now?: Date;
+    /** Optional narrative overrides merged over style defaults. */
+    narratives?: Record<string, string>;
+    items?: unknown[];
+}
+/** Build a minimal valid xBRIEF v0.8 document for the given P0 style. */
+export declare function buildStyleDocument(input: BuildDocumentInput): XbriefDocument;
+/** Render dense markdown from the JSON spine (one dialect). */
+export declare function renderMarkdown(doc: XbriefDocument, style: XbriefStyle): string;
+/**
+ * Lightweight parse of md form for verify: extract title, status, id, and H2 sections.
+ * Not a full reverse dialect — verify uses it for required-section + consistency checks.
+ */
+export declare function parseMarkdownMeta(md: string): {
+    title: string | null;
+    status: string | null;
+    id: string | null;
+    style: string | null;
+    sections: Set<string>;
+};
+//# sourceMappingURL=styles.d.ts.map

package/dist/xbrief/styles.js

@@ -0,0 +1,235 @@
+/**
+ * P0 xBRIEF style templates and markdown section maps (#3057).
+ *
+ * One schema spine (xBRIEF v0.8); markdown is a dense render of the same plan,
+ * not a second dialect.
+ */
+/** Required H2 section titles in the markdown form per style. */
+export const MD_REQUIRED_SECTIONS = {
+    scope: ["Title", "Status", "Overview", "Items"],
+    playbook: ["Title", "Status", "Overview", "Steps"],
+    mission: ["Title", "Status", "Outcome", "Evidence"],
+    project: ["Title", "Status", "Overview", "TechStack"],
+};
+function isoNow(now) {
+    return now.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function defaultStatus(style) {
+    switch (style) {
+        case "scope":
+            return "draft";
+        case "playbook":
+            return "approved";
+        case "mission":
+            return "completed";
+        case "project":
+            return "approved";
+    }
+}
+function defaultNarratives(style, title) {
+    switch (style) {
+        case "scope":
+            return {
+                Overview: `Scope brief for ${title}.`,
+                Description: "",
+            };
+        case "playbook":
+            return {
+                Overview: `Playbook for ${title}.`,
+                Steps: "1. Inspect\n2. Act\n3. Verify",
+            };
+        case "mission":
+            return {
+                Outcome: `Mission outcome for ${title}.`,
+                Evidence: "",
+            };
+        case "project":
+            return {
+                Overview: `Project identity for ${title}.`,
+                TechStack: "",
+            };
+    }
+}
+function defaultItems(style) {
+    if (style === "playbook") {
+        return [
+            {
+                title: "Inspect",
+                status: "proposed",
+                narrative: { Acceptance: "Context is loaded and preconditions hold." },
+            },
+            {
+                title: "Act",
+                status: "proposed",
+                narrative: { Acceptance: "Primary steps complete." },
+            },
+            {
+                title: "Verify",
+                status: "proposed",
+                narrative: { Acceptance: "Checks pass or failures are recorded." },
+            },
+        ];
+    }
+    return [];
+}
+/** Build a minimal valid xBRIEF v0.8 document for the given P0 style. */
+export function buildStyleDocument(input) {
+    const now = input.now ?? new Date();
+    const stamp = isoNow(now);
+    const status = input.status ?? defaultStatus(input.style);
+    const baseNarratives = defaultNarratives(input.style, input.title);
+    const narratives = { ...baseNarratives, ...(input.narratives ?? {}) };
+    const items = input.items ?? defaultItems(input.style);
+    const plan = {
+        title: input.title,
+        status,
+        narratives,
+        items,
+        metadata: {
+            kind: input.style,
+            xbriefCreate: true,
+        },
+    };
+    if (input.id !== undefined && input.id.length > 0) {
+        plan.id = input.id;
+    }
+    return {
+        xBRIEFInfo: {
+            version: "0.8",
+            description: input.description ?? `xBRIEF ${input.style} artifact (on-demand create)`,
+            created: stamp,
+            updated: stamp,
+        },
+        plan,
+    };
+}
+function sectionBody(doc, key) {
+    const narratives = doc.plan.narratives ?? {};
+    // Prefer exact key, then case-insensitive match.
+    if (typeof narratives[key] === "string")
+        return narratives[key];
+    const lower = key.toLowerCase();
+    for (const [k, v] of Object.entries(narratives)) {
+        if (k.toLowerCase() === lower && typeof v === "string")
+            return v;
+    }
+    return "";
+}
+function renderItemsList(doc, heading) {
+    const lines = [`## ${heading}`, ""];
+    const items = Array.isArray(doc.plan.items) ? doc.plan.items : [];
+    if (items.length === 0) {
+        lines.push("_(none)_", "");
+        return lines.join("\n");
+    }
+    for (const raw of items) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            lines.push(`- ${String(raw)}`);
+            continue;
+        }
+        const item = raw;
+        const title = typeof item.title === "string" ? item.title : "(untitled)";
+        const status = typeof item.status === "string" ? item.status : "unknown";
+        lines.push(`- **${title}** (${status})`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/** Render dense markdown from the JSON spine (one dialect). */
+export function renderMarkdown(doc, style) {
+    const idLine = typeof doc.plan.id === "string" && doc.plan.id.length > 0 ? `id: ${doc.plan.id}\n` : "";
+    const header = [
+        "---",
+        "xbrief: 0.8",
+        `style: ${style}`,
+        idLine.trimEnd() === "" ? null : idLine.trimEnd(),
+        "---",
+        "",
+        `# ${doc.plan.title}`,
+        "",
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    const sections = MD_REQUIRED_SECTIONS[style];
+    const parts = [header];
+    for (const section of sections) {
+        if (section === "Title") {
+            parts.push("## Title", "", doc.plan.title, "");
+            continue;
+        }
+        if (section === "Status") {
+            parts.push("## Status", "", String(doc.plan.status), "");
+            continue;
+        }
+        if (section === "Items" || section === "Steps") {
+            parts.push(renderItemsList(doc, section));
+            // Also include narrative Steps when present for playbook density.
+            if (section === "Steps") {
+                const stepsNarrative = sectionBody(doc, "Steps");
+                if (stepsNarrative.length > 0) {
+                    parts.push("### Steps narrative", "", stepsNarrative, "");
+                }
+            }
+            continue;
+        }
+        const body = sectionBody(doc, section);
+        parts.push(`## ${section}`, "", body.length > 0 ? body : "_(empty)_", "");
+    }
+    return `${parts
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd()}\n`;
+}
+/**
+ * Lightweight parse of md form for verify: extract title, status, id, and H2 sections.
+ * Not a full reverse dialect — verify uses it for required-section + consistency checks.
+ */
+export function parseMarkdownMeta(md) {
+    const sections = new Set();
+    let title = null;
+    let status = null;
+    let id = null;
+    let style = null;
+    const lines = md.split(/\r?\n/);
+    let inFront = false;
+    let afterTitleH2 = false;
+    let afterStatusH2 = false;
+    for (const line of lines) {
+        if (line.trim() === "---") {
+            inFront = !inFront;
+            continue;
+        }
+        if (inFront) {
+            const idMatch = /^id:\s*(.+)\s*$/.exec(line);
+            if (idMatch?.[1] !== undefined)
+                id = idMatch[1].trim();
+            const styleMatch = /^style:\s*(.+)\s*$/.exec(line);
+            if (styleMatch?.[1] !== undefined)
+                style = styleMatch[1].trim();
+            continue;
+        }
+        const h1 = /^#\s+(.+)$/.exec(line);
+        if (h1?.[1] !== undefined && title === null) {
+            title = h1[1].trim();
+        }
+        const h2 = /^##\s+(.+)$/.exec(line);
+        if (h2?.[1] !== undefined) {
+            const name = h2[1].trim();
+            sections.add(name);
+            afterTitleH2 = name === "Title";
+            afterStatusH2 = name === "Status";
+            continue;
+        }
+        if (afterTitleH2 && line.trim().length > 0 && !line.startsWith("#")) {
+            // Prefer ## Title body over H1 when present.
+            title = line.trim();
+            afterTitleH2 = false;
+        }
+        if (afterStatusH2 && line.trim().length > 0 && !line.startsWith("#")) {
+            status = line.trim();
+            afterStatusH2 = false;
+        }
+    }
+    return { title, status, id, style, sections };
+}
+//# sourceMappingURL=styles.js.map

package/dist/xbrief/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared types for on-demand xBRIEF create/verify (#3057).
+ *
+ * create/verify write or check shaped SoT artifacts at an explicit path.
+ * They are NOT scope lifecycle verbs (scope:promote / activate / complete).
+ */
+export declare const XBRIEF_FORMATS: readonly ["json", "md", "both"];
+export type XbriefFormat = (typeof XBRIEF_FORMATS)[number];
+export declare const XBRIEF_STYLES: readonly ["scope", "playbook", "mission", "project"];
+export type XbriefStyle = (typeof XBRIEF_STYLES)[number];
+/** Default size cap for create/verify payloads (bytes). */
+export declare const DEFAULT_XBRIEF_SIZE_CAP_BYTES: number;
+export interface XbriefCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface XbriefPaths {
+    /** Absolute project root used for containment. */
+    readonly projectRoot: string;
+    /** Absolute stem path (no .xbrief.json / .xbrief.md suffix). */
+    readonly stemAbs: string;
+    /** Absolute JSON path when format includes json. */
+    readonly jsonAbs: string | null;
+    /** Absolute MD path when format includes md. */
+    readonly mdAbs: string | null;
+}
+export interface XbriefDocument {
+    readonly xBRIEFInfo: {
+        readonly version: "0.8";
+        readonly description?: string;
+        readonly created?: string;
+        readonly updated?: string;
+        readonly author?: string;
+        readonly [key: string]: unknown;
+    };
+    readonly plan: {
+        readonly title: string;
+        readonly status: string;
+        readonly id?: string;
+        readonly narratives?: Record<string, string>;
+        readonly items: unknown[];
+        readonly metadata?: Record<string, unknown>;
+        readonly [key: string]: unknown;
+    };
+    readonly [key: string]: unknown;
+}
+export declare function isXbriefFormat(value: string): value is XbriefFormat;
+export declare function isXbriefStyle(value: string): value is XbriefStyle;
+//# sourceMappingURL=types.d.ts.map

package/dist/xbrief/types.js

@@ -0,0 +1,17 @@
+/**
+ * Shared types for on-demand xBRIEF create/verify (#3057).
+ *
+ * create/verify write or check shaped SoT artifacts at an explicit path.
+ * They are NOT scope lifecycle verbs (scope:promote / activate / complete).
+ */
+export const XBRIEF_FORMATS = ["json", "md", "both"];
+export const XBRIEF_STYLES = ["scope", "playbook", "mission", "project"];
+/** Default size cap for create/verify payloads (bytes). */
+export const DEFAULT_XBRIEF_SIZE_CAP_BYTES = 512 * 1024;
+export function isXbriefFormat(value) {
+    return XBRIEF_FORMATS.includes(value);
+}
+export function isXbriefStyle(value) {
+    return XBRIEF_STYLES.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/xbrief/verify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * xbrief:verify — fail-closed check of an xBRIEF artifact at --out (#3057).
+ *
+ * Required: --format (json|md|both), --out
+ * Checks: schema/parse, required fields, size cap, md sections per style,
+ * and stem/title/id consistency when format=both.
+ *
+ * Does NOT move lifecycle folders.
+ */
+import { type XbriefCliResult, type XbriefFormat, type XbriefStyle } from "./types.js";
+export declare const VERIFY_USAGE: string;
+export interface VerifyOptions {
+    format: XbriefFormat;
+    out: string;
+    style?: XbriefStyle;
+    projectRoot: string;
+    sizeCapBytes?: number;
+    cwd?: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Parse verify CLI argv into options (or error string). */
+export declare function parseVerifyArgv(argv: readonly string[]): VerifyOptions | {
+    error: string;
+};
+/** Core verify implementation (testable). */
+export declare function verifyXbrief(options: VerifyOptions): XbriefCliResult;
+/** CLI entry for dispatch wrapper. */
+export declare function runXbriefVerifyCli(argv: string[]): XbriefCliResult;
+//# sourceMappingURL=verify.d.ts.map