@open-product-primer/cli 1.2.0 → 2.1.0

package/README.md

@@ -27,5 +27,11 @@ Bin aliases: `open-product-primer`, `oprim`.
 | `oprim update` | Refresh `/oprim:*` assistant commands and skills |
 | `oprim doctor` | Verify scaffold, integrations, and measurement env |
 | `oprim measure` | Run KPI measurement pipeline for a bet |
+| `oprim context` | Print resolved remote context content (`--source <name>` to scope to one) |
+| `oprim context init` | Declare the current project a citable remote context (`--description`); prefer the guided `/oprim:context-init` skill in Claude Code |
+| `oprim context register` | Register a remote context source (`--git <url>` or `--local <path>`, `--name`, optional `--description`) |
+| `oprim context list` | List every registered source's name, kind, and description without fully resolving any of them |
+
+A remote context is an oprim workspace bundled somewhere outside the current project's directory — a remote git repo or a local sibling directory — that this project can reference read-only. Content resolves fresh on demand (never a persistent clone you have to `git pull` yourself); `oprim context list` is the cheap way to see what's registered before pulling full content.
 
 Full documentation: [github.com/eshraw/open-product-primer](https://github.com/eshraw/open-product-primer).

package/dist/cli.js

@@ -11,6 +11,7 @@ const doctor_1 = require("./commands/doctor");
 const migrate_1 = require("./commands/migrate");
 const measure_1 = require("./commands/measure");
 const ovw_1 = require("./commands/ovw");
+const context_1 = require("./commands/context");
 const package_json_1 = __importDefault(require("../package.json"));
 const program = new commander_1.Command();
 program
@@ -23,4 +24,5 @@ program.addCommand((0, doctor_1.doctorCommand)());
 program.addCommand((0, migrate_1.migrateCommand)());
 program.addCommand((0, measure_1.measureCommand)());
 program.addCommand((0, ovw_1.ovwCommand)());
+program.addCommand((0, context_1.contextCommand)());
 program.parse();

package/dist/commands/context.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function contextCommand(): Command;

package/dist/commands/context.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextCommand = contextCommand;
+const commander_1 = require("commander");
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const remote_context_1 = require("../lib/remote-context");
+const scaffold_1 = require("../lib/scaffold");
+function sourceKind(source) {
+    return (0, remote_context_1.isGitSource)(source) ? 'git' : 'path';
+}
+function initSubcommand() {
+    return new commander_1.Command('init')
+        .description('Declare the current project as a citable remote context')
+        .option('--description <text>', 'canonical description of what this context contains')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        if ((0, scaffold_1.fileExists)((0, remote_context_1.identityFilePath)(projectRoot))) {
+            console.log(chalk_1.default.yellow('A remote context identity already exists at ') + chalk_1.default.cyan('.oprim-context/context.yaml'));
+            return;
+        }
+        const name = path.basename(projectRoot);
+        (0, remote_context_1.writeIdentity)(projectRoot, { name, version: '1', description: opts.description });
+        console.log(chalk_1.default.green('✓') + ' .oprim-context/context.yaml created');
+        console.log(`  name: ${name}`);
+        if (opts.description) {
+            console.log(`  description: ${opts.description}`);
+        }
+        else {
+            console.log(chalk_1.default.yellow('  no description set') +
+                ' — other projects referencing this context via ' +
+                chalk_1.default.cyan('oprim context list') +
+                ' will see it as description-less.');
+        }
+    });
+}
+function registerSubcommand() {
+    return new commander_1.Command('register')
+        .description('Register a remote context source in the current project')
+        .option('--git <url>', 'git remote URL of the remote context')
+        .option('--local <path>', 'local filesystem path of the remote context')
+        .requiredOption('--name <name>', 'name to register this source under')
+        .option('--description <text>', 'local note about why this source was registered')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        if ((opts.git && opts.local) || (!opts.git && !opts.local)) {
+            console.error(chalk_1.default.red('Exactly one of --git or --local is required.'));
+            process.exit(1);
+        }
+        const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+        if ((0, remote_context_1.findSourceByName)(config, opts.name)) {
+            console.error(chalk_1.default.red(`A source named "${opts.name}" is already registered.`));
+            process.exit(1);
+        }
+        const source = opts.git
+            ? { name: opts.name, git: opts.git, description: opts.description }
+            : { name: opts.name, path: opts.local, description: opts.description };
+        config.enabled = true;
+        config.sources.push(source);
+        (0, remote_context_1.writeRemoteContextConfig)(projectRoot, config);
+        console.log(chalk_1.default.green('✓') + ` Registered "${opts.name}" (${sourceKind(source)})`);
+        const result = (0, remote_context_1.resolveIdentityOnly)(source);
+        if (result.error) {
+            console.log(chalk_1.default.yellow('  Could not confirm this source yet: ') +
+                result.error +
+                chalk_1.default.dim(' — try `oprim context list` or `oprim doctor` to retry later.'));
+            return;
+        }
+        if (result.nameMismatch) {
+            console.log(chalk_1.default.yellow(`  Warning: declared name "${result.nameMismatch.declared}" does not match resolved identity name "${result.nameMismatch.resolved}".`));
+        }
+        if (result.identity?.description) {
+            console.log(`  ${chalk_1.default.dim('description:')} ${result.identity.description}`);
+        }
+        else {
+            console.log(chalk_1.default.dim('  (no canonical description set on this source)'));
+        }
+    });
+}
+function listSubcommand() {
+    return new commander_1.Command('list')
+        .description('List every registered remote context source, without fully resolving any of them')
+        .action(() => {
+        const projectRoot = process.cwd();
+        const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+        if (!config.enabled || config.sources.length === 0) {
+            console.log('No remote contexts configured.');
+            return;
+        }
+        for (const source of config.sources) {
+            const kind = sourceKind(source);
+            console.log(`${chalk_1.default.bold(source.name)} ${chalk_1.default.dim(`(${kind})`)}`);
+            const result = (0, remote_context_1.resolveIdentityOnly)(source);
+            if (result.error) {
+                console.log('  ' + chalk_1.default.red(`unresolved: ${result.error}`));
+            }
+            else {
+                const desc = result.identity?.description;
+                console.log('  ' + (desc ? desc : chalk_1.default.dim('no description set')));
+                if (result.nameMismatch) {
+                    console.log(chalk_1.default.yellow(`  name mismatch: declared "${result.nameMismatch.declared}", resolved "${result.nameMismatch.resolved}"`));
+                }
+            }
+            if (source.description) {
+                console.log('  ' + chalk_1.default.dim(`local note: ${source.description}`));
+            }
+            console.log('');
+        }
+    });
+}
+function contextCommand() {
+    const cmd = new commander_1.Command('context')
+        .description('Print resolved remote context content')
+        .option('--source <name>', 'limit output to a single named source')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+        if (!config.enabled || config.sources.length === 0) {
+            console.log('No remote contexts configured.');
+            return;
+        }
+        let sources = config.sources;
+        if (opts.source) {
+            const match = (0, remote_context_1.findSourceByName)(config, opts.source);
+            if (!match) {
+                console.error(chalk_1.default.red(`No source named "${opts.source}" is registered.`));
+                process.exit(1);
+            }
+            sources = [match];
+        }
+        for (const source of sources) {
+            console.log(chalk_1.default.bold(`═══ ${source.name} ═══`));
+            const result = (0, remote_context_1.resolveFull)(source);
+            if (result.error) {
+                console.log(chalk_1.default.red(`  unresolved: ${result.error}`));
+                continue;
+            }
+            if (result.stale) {
+                console.log(chalk_1.default.yellow('  (stale — last successful fetch could not be refreshed)'));
+            }
+            if (result.nameMismatch) {
+                console.log(chalk_1.default.yellow(`  name mismatch: declared "${result.nameMismatch.declared}", resolved "${result.nameMismatch.resolved}"`));
+            }
+            console.log((0, remote_context_1.assembleOprimWorkspaceContent)(result.workspaceRoot));
+            console.log('');
+        }
+    });
+    cmd.addCommand(initSubcommand());
+    cmd.addCommand(registerSubcommand());
+    cmd.addCommand(listSubcommand());
+    return cmd;
+}

package/dist/commands/doctor.js

@@ -44,6 +44,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const detect_1 = require("../lib/detect");
 const measure_1 = require("../lib/measure");
 const integrity_1 = require("../lib/integrity");
+const remote_context_1 = require("../lib/remote-context");
 const AGENT_DIRS = {
     claude: '.claude',
     cursor: '.cursor',
@@ -103,6 +104,52 @@ function checkClaudeHooks(projectRoot, checks) {
         required: false,
     });
 }
+// bet-026 — validates each configured remote_context.sources entry using the identity-only
+// fetch (cheap: single file, not a full workspace pull), plus a separate "ever fully
+// resolved" nudge that only applies to git sources (local paths have no persistent cache).
+function checkRemoteContexts(projectRoot, checks) {
+    const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+    if (!config.enabled || config.sources.length === 0)
+        return;
+    for (const source of config.sources) {
+        const kind = (0, remote_context_1.isGitSource)(source) ? 'git' : 'path';
+        const result = (0, remote_context_1.resolveIdentityOnly)(source);
+        if (result.error) {
+            checks.push({
+                name: `remote_context: ${source.name} (${kind})`,
+                pass: false,
+                note: `${kind === 'git' ? 'Remote unreachable' : 'Path not found'}: ${result.error} — run 'oprim context list' to retry`,
+                required: false,
+            });
+            continue;
+        }
+        if (!result.identity) {
+            checks.push({
+                name: `remote_context: ${source.name} (${kind})`,
+                pass: false,
+                note: `Missing remote context identity — ask the source project to run 'oprim context init'`,
+                required: false,
+            });
+            continue;
+        }
+        checks.push({
+            name: `remote_context: ${source.name} (${kind})`,
+            pass: true,
+            note: result.nameMismatch
+                ? `Name mismatch: declared "${result.nameMismatch.declared}", resolved "${result.nameMismatch.resolved}"`
+                : undefined,
+            required: false,
+        });
+        if ((0, remote_context_1.isGitSource)(source) && !(0, remote_context_1.hasEverFullyResolved)(source)) {
+            checks.push({
+                name: `remote_context: ${source.name} never fully resolved`,
+                pass: false,
+                note: `Run 'oprim context --source ${source.name}' to pull its content for the first time`,
+                required: false,
+            });
+        }
+    }
+}
 function doctorCommand() {
     return new commander_1.Command('doctor')
         .description('Check oprim install health and integration readiness')
@@ -209,6 +256,8 @@ function doctorCommand() {
         (0, integrity_1.checkSequenceIntegrity)(projectRoot, checks);
         // ── Skill version drift checks ────────────────────────────────────────────
         (0, integrity_1.checkSkillVersionDrift)(projectRoot, checks);
+        // ── Remote context checks ─────────────────────────────────────────────────
+        checkRemoteContexts(projectRoot, checks);
         // ── Agent environment checks ──────────────────────────────────────────────
         const configAgents = (0, detect_1.readAgentsFromConfig)(projectRoot);
         if (configAgents !== null) {

package/dist/commands/init.js

@@ -61,6 +61,7 @@ function initCommand() {
             console.log(chalk_1.default.green('✓') + ' Graphify detected');
         console.log('');
         const okfEnabled = await (0, install_agent_1.promptOkfFrontmatter)();
+        const specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
         const primerDir = path.join(projectRoot, 'oprim');
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'decisions'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'bets'));
@@ -68,7 +69,7 @@ function initCommand() {
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'notes'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'templates'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'scripts'));
-        const configWritten = (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'config.yaml'), (0, templates_1.configTemplate)(projectName, openspec.detected, graphify.detected, okfEnabled));
+        const configWritten = (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'config.yaml'), (0, templates_1.configTemplate)(projectName, openspec.detected, graphify.detected, okfEnabled, specFramework));
         const sequenceWritten = (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'sequence.yaml'), templates_1.sequenceTemplate);
         const pdrContent = okfEnabled ? (0, templates_1.okfFrontmatter)('pdr', '<Decision title>') + templates_1.pdrTemplate : templates_1.pdrTemplate;
         const betContent = okfEnabled
@@ -136,10 +137,8 @@ function initCommand() {
                 ' after configuring an AI tool to install /oprim:* skills.');
         }
         else {
-            let specFramework = 'openspec';
             let pdrSurfacing = false;
             if (selectedAgents.includes('claude')) {
-                specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
                 pdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
             }
             console.log('\n' + chalk_1.default.bold('Installing agent skills...'));

package/dist/commands/update.js

@@ -45,6 +45,19 @@ const install_agent_1 = require("../lib/install-agent");
 const detect_1 = require("../lib/detect");
 const scaffold_1 = require("../lib/scaffold");
 const templates_1 = require("../lib/templates");
+const config_merge_1 = require("../lib/config-merge");
+// bet-023 — persist the resolved spec_framework into oprim/config.yaml, inserting it only
+// when the key is missing (never overwrites an already-persisted choice).
+function persistSpecFramework(configPath, framework) {
+    if (!fs.existsSync(configPath))
+        return;
+    const existing = fs.readFileSync(configPath, 'utf-8');
+    const { content, changed } = (0, config_merge_1.mergeSpecFramework)(existing, framework);
+    if (changed) {
+        fs.writeFileSync(configPath, content, 'utf-8');
+        console.log(chalk_1.default.green('✓') + ` oprim/config.yaml — integrations.spec_framework set to ${framework}`);
+    }
+}
 function updateCommand() {
     return new commander_1.Command('update')
         .description('Refresh /oprim:* assistant commands and skills from package templates')
@@ -58,13 +71,23 @@ function updateCommand() {
         const primerDir = path.join(projectRoot, 'oprim');
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'scripts'));
         (0, scaffold_1.writeFile)(path.join(primerDir, 'scripts', 'generate-sequence-view.js'), templates_1.sequenceViewScriptTemplate);
+        const configPath = path.join(primerDir, 'config.yaml');
+        if (fs.existsSync(configPath)) {
+            const existingConfig = fs.readFileSync(configPath, 'utf-8');
+            const { content: mergedConfig, changed } = (0, config_merge_1.mergeConfigSchema)(existingConfig);
+            if (changed) {
+                fs.writeFileSync(configPath, mergedConfig, 'utf-8');
+                console.log(chalk_1.default.green('✓') + ' oprim/config.yaml — schema updated with new keys (existing values preserved)');
+            }
+        }
         if (configAgents !== null && configAgents.length > 0) {
-            let specFramework = 'openspec';
+            let specFramework = (0, install_agent_1.resolveSpecFramework)(projectRoot);
             let pdrSurfacing = false;
             if (configAgents.includes('claude')) {
                 specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
                 pdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
             }
+            persistSpecFramework(configPath, specFramework);
             for (const agent of configAgents) {
                 (0, install_agent_1.installAgentSkills)(agent, projectRoot, specFramework, pdrSurfacing);
             }
@@ -75,6 +98,7 @@ function updateCommand() {
             const legacyAgents = [];
             if (fs.existsSync(path.join(projectRoot, '.claude'))) {
                 const specFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
+                persistSpecFramework(configPath, specFramework);
                 const pdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
                 (0, install_agent_1.installAgentSkills)('claude', projectRoot, specFramework, pdrSurfacing);
                 legacyAgents.push('claude');
@@ -99,22 +123,25 @@ function updateCommand() {
             default: false,
         });
         if (!addMore) {
+            persistSpecFramework(configPath, (0, install_agent_1.resolveSpecFramework)(projectRoot));
             console.log('\nRun ' + chalk_1.default.cyan('oprim doctor') + ' to verify your setup.');
             return;
         }
         console.log('');
         const selected = await (0, install_agent_1.promptAgentSelection)(projectRoot);
         if (selected.length === 0) {
+            persistSpecFramework(configPath, (0, install_agent_1.resolveSpecFramework)(projectRoot));
             console.log('\n' + chalk_1.default.yellow('No agents selected.'));
             console.log('\nRun ' + chalk_1.default.cyan('oprim doctor') + ' to verify your setup.');
             return;
         }
-        let addSpecFramework = 'openspec';
+        let addSpecFramework = (0, install_agent_1.resolveSpecFramework)(projectRoot);
         let addPdrSurfacing = false;
         if (selected.includes('claude')) {
             addSpecFramework = await (0, install_agent_1.promptFrameworkSelection)(projectRoot);
             addPdrSurfacing = await (0, install_agent_1.promptPdrSurfacing)();
         }
+        persistSpecFramework(configPath, addSpecFramework);
         console.log('\n' + chalk_1.default.bold('Installing agent skills...'));
         for (const agent of selected) {
             (0, install_agent_1.installAgentSkills)(agent, projectRoot, addSpecFramework, addPdrSurfacing);

package/dist/lib/config-merge.d.ts

@@ -0,0 +1,10 @@
+export declare function mergeConfigSchema(existingContent: string): {
+    content: string;
+    changed: boolean;
+};
+export declare function readSpecFramework(content: string): string | null;
+export declare function deriveDefaultSpecFramework(content: string): string;
+export declare function mergeSpecFramework(existingContent: string, framework: string): {
+    content: string;
+    changed: boolean;
+};

package/dist/lib/config-merge.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeConfigSchema = mergeConfigSchema;
+exports.readSpecFramework = readSpecFramework;
+exports.deriveDefaultSpecFramework = deriveDefaultSpecFramework;
+exports.mergeSpecFramework = mergeSpecFramework;
+const CONFIG_SCHEMA_FIELDS = [
+    { key: 'context', block: 'context: ""\n' },
+    { key: 'rules', block: 'rules: {}\n' },
+    // bet-026 — supersedes the old inert `store:` key (BET-025). `store` is intentionally left
+    // out of this table going forward: a project that already has it keeps it untouched (this
+    // merge only adds missing keys, never removes existing ones), but new/updated configs only
+    // ever gain `remote_context`.
+    { key: 'remote_context', block: 'remote_context:\n  enabled: false\n  sources: []\n' },
+];
+function existingTopLevelKeys(content) {
+    const keys = new Set();
+    for (const line of content.split('\n')) {
+        const match = line.match(/^([A-Za-z_][\w-]*):/);
+        if (match)
+            keys.add(match[1]);
+    }
+    return keys;
+}
+function mergeConfigSchema(existingContent) {
+    const present = existingTopLevelKeys(existingContent);
+    const missing = CONFIG_SCHEMA_FIELDS.filter((field) => !present.has(field.key));
+    if (missing.length === 0)
+        return { content: existingContent, changed: false };
+    const separator = existingContent.endsWith('\n') ? '' : '\n';
+    const additions = missing.map((field) => field.block).join('');
+    return { content: existingContent + separator + additions, changed: true };
+}
+// bet-023 — integrations.spec_framework is nested under `integrations:` rather than a
+// top-level key, and its default depends on the project's existing openspec state, so it
+// can't reuse the static CONFIG_SCHEMA_FIELDS table above. Handled as its own one-off per
+// the bet's design (falls back to a minimal merge rather than depending on the generic
+// top-level mechanism, which doesn't support nested keys or computed defaults).
+function readSpecFramework(content) {
+    const match = content.match(/^\s*spec_framework:\s*(\S+)/m);
+    return match ? match[1] : null;
+}
+function deriveDefaultSpecFramework(content) {
+    return /^\s*openspec:\n\s*enabled:\s*true/m.test(content) ? 'openspec' : 'none';
+}
+function mergeSpecFramework(existingContent, framework) {
+    if (readSpecFramework(existingContent))
+        return { content: existingContent, changed: false };
+    const lines = existingContent.split('\n');
+    const integrationsIndex = lines.findIndex((line) => line === 'integrations:');
+    if (integrationsIndex === -1) {
+        const separator = existingContent.endsWith('\n') ? '' : '\n';
+        return { content: existingContent + separator + `integrations:\n  spec_framework: ${framework}\n`, changed: true };
+    }
+    lines.splice(integrationsIndex + 1, 0, `  spec_framework: ${framework}`);
+    return { content: lines.join('\n'), changed: true };
+}

package/dist/lib/install-agent.d.ts

@@ -1,6 +1,7 @@
 export type Agent = 'claude' | 'cursor' | 'codex' | 'gemini' | 'poolside';
 export declare const SUPPORTED_AGENTS: readonly Agent[];
 export declare function promptFrameworkSelection(projectRoot: string): Promise<string>;
+export declare function resolveSpecFramework(projectRoot: string): string;
 export declare function promptAgentSelection(projectRoot: string): Promise<string[]>;
 export declare function promptPdrSurfacing(): Promise<boolean>;
 export declare function promptOkfFrontmatter(): Promise<boolean>;
@@ -11,6 +12,7 @@ export declare const CLAUDE_COMMANDS: Record<string, string>;
 export declare const POOLSIDE_SKILLS: Record<string, string>;
 export declare const CURSOR_SKILLS: Record<string, string>;
 export declare const CURSOR_COMMANDS: Record<string, string>;
+export declare function specAuthoringSkill(): string;
 export declare function writeAgentInstructionFile(filePath: string, section: string): void;
 export declare function codexInstructions(): string;
 export declare function geminiInstructions(): string;