@productbrain/cli 0.1.0-beta.15 → 0.1.0-beta.1502

package/dist/generators/manifest.js

@@ -0,0 +1,277 @@
+/**
+ * Manifest reader — reads .productbrain/manifest.yaml for adoption state.
+ * WP-310 E1: personal workspace layer — manifest-based filtering.
+ * WP-421 S1 (#35): extends Manifest with DEC-951 authority keys (`materialize`,
+ * `surfaces`, `lock`) and adds `readManifestStatus()` — a typed reader that
+ * returns the FULL UNION of legacy + new fields plus a `parseStatus`
+ * discriminator (DEC-955, DEC-963 "Authority mode parse semantics").
+ *
+ * No external YAML dependency is required; the manifest schema is
+ * simple enough to parse with a minimal line-by-line parser.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+// ── Minimal YAML parser ────────────────────────────────────────────────
+//
+// Handles the subset of YAML used by manifest.yaml:
+//   - Top-level key: value pairs (strings, booleans)
+//   - Nested objects (one level deep, e.g. hooks.cursor: true)
+//   - Sequence lists under a key:
+//       adopted:
+//         - rule-a
+//         - rule-b
+//
+// Does NOT handle: multi-line strings, anchors, complex quoting, etc.
+function parseManifestYaml(raw) {
+    const result = {};
+    const lines = raw.split('\n');
+    let currentKey = null;
+    let currentArray = null;
+    let currentObject = null;
+    const commitCurrent = () => {
+        if (currentKey !== null) {
+            if (currentArray !== null) {
+                result[currentKey] = currentArray;
+            }
+            else if (currentObject !== null) {
+                result[currentKey] = currentObject;
+            }
+        }
+        currentKey = null;
+        currentArray = null;
+        currentObject = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const rawLine = lines[i];
+        const line = rawLine;
+        // Skip comments and blank lines
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        // Array item: "  - value"
+        const arrayItemMatch = line.match(/^(\s+)-\s+(.+)$/);
+        if (arrayItemMatch && currentKey !== null) {
+            const indent = arrayItemMatch[1].length;
+            const value = arrayItemMatch[2].trim().replace(/^['"]|['"]$/g, '');
+            if (indent >= 2) {
+                if (currentArray !== null) {
+                    currentArray.push(value);
+                    continue;
+                }
+            }
+        }
+        // Nested key-value: "  key: value"
+        const nestedKvMatch = line.match(/^(\s{2,})([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+        if (nestedKvMatch && currentKey !== null) {
+            if (currentObject === null) {
+                // Transition: previous currentArray (if any) is lost — nested objects start fresh
+                currentArray = null;
+                currentObject = {};
+            }
+            const nestedVal = nestedKvMatch[3].trim();
+            currentObject[nestedKvMatch[2]] = parseScalar(nestedVal);
+            continue;
+        }
+        // Top-level key: value
+        const kvMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+        if (kvMatch) {
+            commitCurrent();
+            const key = kvMatch[1];
+            const val = kvMatch[2].trim();
+            if (val === '') {
+                // Value will come on subsequent lines (array or object)
+                currentKey = key;
+                currentArray = null;
+                currentObject = null;
+                // Peek ahead using index — avoid indexOf which breaks on duplicate lines
+                const nextContent = lines.slice(i + 1).find((l) => l.trim() && !l.trim().startsWith('#'));
+                if (nextContent && nextContent.match(/^\s+-\s+/)) {
+                    currentArray = [];
+                }
+                else if (nextContent && nextContent.match(/^\s{2,}[a-zA-Z]/)) {
+                    currentObject = {};
+                }
+            }
+            else {
+                result[key] = parseScalar(val);
+            }
+            continue;
+        }
+    }
+    commitCurrent();
+    return result;
+}
+function parseScalar(val) {
+    const stripped = val.replace(/^['"]|['"]$/g, '');
+    if (stripped === 'true')
+        return true;
+    if (stripped === 'false')
+        return false;
+    if (stripped === 'null' || stripped === '~')
+        return null;
+    if (/^\d+$/.test(stripped))
+        return parseInt(stripped, 10);
+    return stripped;
+}
+// ── Public API ─────────────────────────────────────────────────────────
+/** Valid AuthorityMode values, derived once for runtime guards. */
+const VALID_AUTHORITY_MODES = new Set([
+    'off',
+    'observe',
+    'project',
+    'govern',
+]);
+/** Valid LockLevel values. */
+const VALID_LOCK_LEVELS = new Set([
+    'platform',
+    'workspace',
+    'personal',
+]);
+/**
+ * Validate a parsed manifest object against the union schema.
+ * Returns the typed Manifest on success, null on any shape violation.
+ *
+ * Shared between `readManifest()` and `readManifestStatus()` so legacy
+ * callers and the WP-421 typed reader agree on what counts as parseable.
+ */
+function validateManifestShape(parsed) {
+    // Require version to be a string; reject missing or non-string values
+    if (typeof parsed.version !== 'string')
+        return null;
+    // Validate array fields — scalar values (e.g. adopted: "rule-a") must be rejected
+    if (parsed.adopted !== undefined && !Array.isArray(parsed.adopted))
+        return null;
+    if (parsed.rejected !== undefined && !Array.isArray(parsed.rejected))
+        return null;
+    // Validate method_source if present — only 'chain' | 'bundled' are valid
+    if (parsed.method_source !== undefined &&
+        parsed.method_source !== 'chain' &&
+        parsed.method_source !== 'bundled')
+        return null;
+    // ── WP-421 S1 — DEC-951 keys ─────────────────────────────────────────
+    // materialize: optional; if present, must be a known AuthorityMode.
+    if (parsed.materialize !== undefined &&
+        !(typeof parsed.materialize === 'string' && VALID_AUTHORITY_MODES.has(parsed.materialize))) {
+        return null;
+    }
+    // surfaces: optional; if present, must be an array of strings.
+    if (parsed.surfaces !== undefined) {
+        if (!Array.isArray(parsed.surfaces))
+            return null;
+        if (!parsed.surfaces.every((s) => typeof s === 'string'))
+            return null;
+    }
+    // lock: optional; if present, must be a plain object whose values are valid LockLevels.
+    if (parsed.lock !== undefined) {
+        if (parsed.lock === null ||
+            typeof parsed.lock !== 'object' ||
+            Array.isArray(parsed.lock)) {
+            return null;
+        }
+        for (const value of Object.values(parsed.lock)) {
+            if (typeof value !== 'string' || !VALID_LOCK_LEVELS.has(value)) {
+                return null;
+            }
+        }
+    }
+    return parsed;
+}
+/**
+ * Read .productbrain/manifest.yaml.
+ * Returns null if the file is absent or unparseable (treat as no-op).
+ *
+ * Legacy reader — kept for callers that only need adoption-state filtering.
+ * WP-421 callers should prefer `readManifestStatus()` for typed authority
+ * mode + parse-status discriminator.
+ */
+export function readManifest(productbrainDir) {
+    const manifestPath = join(productbrainDir, 'manifest.yaml');
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = readFileSync(manifestPath, 'utf8');
+        const parsed = parseManifestYaml(raw);
+        return validateManifestShape(parsed);
+    }
+    catch {
+        return null; // malformed manifest = treat as absent
+    }
+}
+/**
+ * Read manifest with full WP-421 authority typing (#35).
+ *
+ * Returns the FULL UNION of legacy + DEC-951 keys plus a `parseStatus`
+ * discriminator. Defaults per DEC-955 / DEC-963:
+ *   - `.productbrain/` directory absent → mode='off', parseStatus='absent'
+ *   - Directory present, manifest absent → mode='observe', parseStatus='absent'
+ *   - Manifest present, no `materialize:` → mode='observe', parseStatus='ok'
+ *   - Manifest unparseable / fails shape validation → mode='observe',
+ *     parseStatus='unparseable' (NEVER 'project'/'govern' — fail closed).
+ *
+ * @param productbrainDir Absolute path to the `.productbrain/` directory.
+ *   The directory itself MAY be absent — caller passes the candidate path
+ *   regardless and this reader infers the mode from filesystem state.
+ */
+export function readManifestStatus(productbrainDir) {
+    // No `.productbrain/` directory at all → mode 'off' (DEC-955).
+    if (!existsSync(productbrainDir)) {
+        return { mode: 'off', surfaces: [], lock: {}, parseStatus: 'absent', manifest: null };
+    }
+    const manifestPath = join(productbrainDir, 'manifest.yaml');
+    // Directory present but no manifest file → mode 'observe', absent.
+    if (!existsSync(manifestPath)) {
+        return { mode: 'observe', surfaces: [], lock: {}, parseStatus: 'absent', manifest: null };
+    }
+    let raw;
+    try {
+        raw = readFileSync(manifestPath, 'utf8');
+    }
+    catch {
+        // I/O failure — treat as unparseable, fail closed to observe (DEC-963).
+        return { mode: 'observe', surfaces: [], lock: {}, parseStatus: 'unparseable', manifest: null };
+    }
+    let parsed;
+    try {
+        parsed = parseManifestYaml(raw);
+    }
+    catch {
+        return { mode: 'observe', surfaces: [], lock: {}, parseStatus: 'unparseable', manifest: null };
+    }
+    const validated = validateManifestShape(parsed);
+    if (validated === null) {
+        // Shape violation (e.g. invalid materialize value, malformed lock map).
+        // Fail closed to observe per DEC-963 — NEVER project/govern.
+        return { mode: 'observe', surfaces: [], lock: {}, parseStatus: 'unparseable', manifest: null };
+    }
+    return {
+        mode: validated.materialize ?? 'observe',
+        surfaces: validated.surfaces ?? [],
+        lock: validated.lock ?? {},
+        parseStatus: 'ok',
+        manifest: validated,
+    };
+}
+/**
+ * Filter a list of items by the manifest's adopted/rejected lists.
+ *
+ * Rules:
+ * - No manifest → return all items unchanged (no-op, preserves current behaviour).
+ * - rejected denylist applied first — excluded regardless of adopted.
+ * - adopted allowlist applied second — only items in the list pass (only when non-empty).
+ * - Empty adopted array → allowlist is inactive, all non-rejected items pass.
+ */
+export function filterByAdoptionState(items, manifest) {
+    if (!manifest)
+        return items;
+    const adopted = manifest.adopted ?? [];
+    const rejected = new Set(manifest.rejected ?? []);
+    // Apply rejected denylist first
+    let filtered = items.filter((item) => !rejected.has(item.name));
+    // Apply adopted allowlist (only when non-empty)
+    if (adopted.length > 0) {
+        const adoptedSet = new Set(adopted);
+        filtered = filtered.filter((item) => adoptedSet.has(item.name));
+    }
+    return filtered;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/generators/manifest.js.map

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

package/dist/generators/portable-knowledge.d.ts

@@ -2,6 +2,13 @@
  * Portable knowledge — reads canonical skills/rules from .productbrain/
  * and generates tool-specific copies for Cursor, Claude Code, etc.
  */
+import type { SurfaceProfile, TargetName } from './surface-profiles.js';
+export type { TargetName };
+export interface WhenConditions {
+    when_stack?: string;
+    when_minStage?: string;
+    when_minGovernance?: string;
+}
 export interface CanonicalSkill {
     name: string;
     description: string;
@@ -10,6 +17,9 @@ export interface CanonicalSkill {
     sourcePath: string;
     targets?: string[];
     level?: string;
+    conditions?: WhenConditions;
+    /** 'team' = default; 'local' = local surface files only, never committed. */
+    persist?: 'local' | 'team';
 }
 export interface CanonicalRule {
     name: string;
@@ -20,22 +30,62 @@ export interface CanonicalRule {
     sourcePath: string;
     targets?: string[];
     level?: string;
+    conditions?: WhenConditions;
+    /** 'team' = default; 'local' = local surface files only, never committed. */
+    persist?: 'local' | 'team';
 }
-export type TargetName = 'cursor' | 'claude' | 'copilot';
 /** Returns true if the entry should be emitted to the given target. */
 export declare function shouldEmitToTarget(entry: CanonicalRule | CanonicalSkill, target: TargetName): boolean;
 export type HandshakeLevel = 'beginner' | 'intermediate' | 'expert';
 /**
- * Filter items by graduated level.
- * - If requestedLevel is undefined/null: return ALL items (backward compat).
+ * Maps workspace stage to the maximum allowed HandshakeLevel.
+ * Stages not listed here apply no cap (fail-open for unknown stages).
+ * Note: 'beginner' level allows only 'core' items; 'intermediate' allows core + intermediate.
+ */
+export declare const STAGE_TO_MAX_LEVEL: Record<string, HandshakeLevel>;
+/** Level ordering used to pick the more restrictive of two levels. */
+export declare const LEVEL_ORDER: HandshakeLevel[];
+/**
+ * Filter items by graduated level, with optional workspace stage-gating.
+ * - If requestedLevel is undefined/null AND stage provides no cap: return ALL items (backward compat).
  * - Items with no `level` field: always included (backward compat).
- * - Otherwise: include items whose level is within the hierarchy for requestedLevel.
+ * - Stage caps the effective level: blank→beginner, seed→intermediate, grounded/connected/critical→expert.
+ * - If stage is unknown or null: no cap applied (fail-open).
+ * - The effective level is min(requestedLevel, stageCap) — most restrictive wins.
  */
 export declare function filterByLevel<T extends {
     level?: string;
-}>(items: T[], requestedLevel?: string): T[];
+}>(items: T[], requestedLevel?: string, stage?: string): T[];
+/**
+ * Evaluate when_* conditions against the workspace profile and repo context.
+ * Returns { included, reasons }.
+ *
+ * Fail-open: if profile is null and profile-dependent conditions are present,
+ * the item is included (preserves current behavior when Chain is unavailable).
+ */
+export declare function evaluateConditions(conditions: WhenConditions, profile: {
+    stage: string;
+    totalRelations: number;
+} | null, repoContext: {
+    detectedStack: string[];
+}): {
+    included: boolean;
+    reasons: string[];
+};
 export declare function readCanonicalSkills(productbrainDir: string): CanonicalSkill[];
 export declare function readCanonicalRules(productbrainDir: string): CanonicalRule[];
+/**
+ * Read machine-local personal rules from .productbrain/.local/rules/.
+ * Returns [] when the directory is absent — no-op when personal layer is not set up.
+ * Every returned rule has persist: 'local' set, marking it as part of the personal layer.
+ */
+export declare function readPersonalLayer(productbrainDir: string): CanonicalRule[];
+/**
+ * Read machine-local personal skills from .productbrain/.local/skills/.
+ * Returns [] when the directory is absent — no-op when personal layer is not set up.
+ * Every returned skill has persist: 'local' set, marking it as part of the personal layer.
+ */
+export declare function readPersonalSkillsLayer(productbrainDir: string): CanonicalSkill[];
 /**
  * Strip transport-conditional sections from a skill body.
  *
@@ -53,20 +103,57 @@ export declare function stripTransportSections(body: string, target: TargetName)
  * Generate a Cursor SKILL.md from a canonical skill.
  * Cursor expects: name, description (with triggers embedded).
  */
-export declare function generateCursorSkill(skill: CanonicalSkill): string;
+export declare function generateCursorSkill(skill: CanonicalSkill, profile?: SurfaceProfile): string;
 /**
  * Generate a Cursor .mdc rule from a canonical rule.
  * Cursor expects: description, globs, alwaysApply.
  */
-export declare function generateCursorRule(rule: CanonicalRule): string;
+export declare function generateCursorRule(rule: CanonicalRule, profile?: SurfaceProfile): string;
+/**
+ * Apply batch-mode transformations to a skill body (DEC-283).
+ *
+ * Skills describe WHAT (intent). This generator produces HOW (batch-appropriate
+ * instructions). We transform interactive patterns without gutting the skill's
+ * logical structure and purpose.
+ *
+ * Transformations applied:
+ * 1. Strip sub-agent spawn patterns → inline steps
+ * 2. Strip user confirmation gates → autonomous proceed
+ * 3. Strip streaming/interactive references
+ * 4. Add batch governance header after first `#` heading
+ */
+export declare function applyBatchTransformations(body: string): string;
+/**
+ * Generate a Codex skill projection from a canonical skill.
+ * This is a repo-local markdown projection, not a separate authoring source.
+ *
+ * When profile.executionModel === 'batch', batch transformations are applied
+ * AFTER transport stripping and path replacement (DEC-283).
+ */
+export declare function generateCodexSkill(skill: CanonicalSkill, profile?: SurfaceProfile): string;
+/**
+ * Generate a Codex skill index/router file.
+ * AGENTS.md can point here so Codex has one obvious place to find available workflows.
+ */
+export declare function generateCodexSkillIndex(skills: CanonicalSkill[]): string;
+export interface CodexValidationWarning {
+    skillName: string;
+    pattern: string;
+    line: string;
+}
+/**
+ * Validate Codex-projected skills for references to capabilities Codex cannot execute.
+ * Scans the transport-stripped body (so claude-only blocks don't false-positive).
+ */
+export declare function validateCodexSkills(skills: CanonicalSkill[]): CodexValidationWarning[];
 /**
  * Generate a Claude Code .md rule from a canonical rule.
  * Claude Code expects: description, optional paths (array).
  */
-export declare function generateClaudeRule(rule: CanonicalRule): string;
+export declare function generateClaudeRule(rule: CanonicalRule, profile?: SurfaceProfile): string;
 /**
  * Generate a Claude Code skill-router.md — imperative skill activation rule.
  * Loaded automatically by Claude Code via .claude/rules/ with no paths (always active).
  */
-export declare function generateClaudeSkillRouter(skills: CanonicalSkill[]): string;
+export declare function generateClaudeSkillRouter(skills: CanonicalSkill[], profile?: SurfaceProfile): string;
 //# sourceMappingURL=portable-knowledge.d.ts.map

package/dist/generators/portable-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portable-knowledge.d.ts","sourceRoot":"","sources":["../../src/generators/portable-knowledge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAGrG;AAID,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,cAAc,GAAG,QAAQ,CAAC;AAUpE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CASpG;AAkED,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,cAAc,EAAE,CAsB7E;AAED,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,aAAa,EAAE,CAuB3E;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAa/E;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAyBjE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAc9D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAqB9D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CA4B1E"}
+{"version":3,"file":"portable-knowledge.d.ts","sourceRoot":"","sources":["../../src/generators/portable-knowledge.ts"],"names":[],"mappings":"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"}