gmc-openspec 1.0.0 → 1.4.1

package/dist/commands/initiative.js

@@ -0,0 +1,318 @@
+import chalk from 'chalk';
+import { createInitiative, INITIATIVE_FILE_NAMES, listInitiativeViewReferences, mountInitiativesCollection, initiativeDiagnosticFromError as coreInitiativeDiagnosticFromError, resolveInitiativeViewReference as resolveCoreInitiativeViewReference, selectContextStoreForInitiative, formatContextStoreSelector, } from '../core/collections/initiatives/index.js';
+export class InitiativeCliError extends Error {
+    diagnostic;
+    constructor(message, code, options = {}) {
+        super(message);
+        this.diagnostic = {
+            severity: 'error',
+            code,
+            message,
+            ...options,
+        };
+    }
+}
+function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function initiativeDiagnosticFromError(error) {
+    if (error instanceof InitiativeCliError) {
+        return error.diagnostic;
+    }
+    return coreInitiativeDiagnosticFromError(error);
+}
+function appendDiagnostic(payload, diagnostic) {
+    return {
+        ...payload,
+        status: [...payload.status, diagnostic],
+    };
+}
+function requireNonBlankOption(value, flagName, target, code) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new InitiativeCliError(`Pass --${flagName} <value>.`, code, {
+            target,
+            fix: `openspec initiative create <id> --${flagName} <value>`,
+        });
+    }
+    return value.trim();
+}
+function requireInitiativeId(id, commandName) {
+    if (id === undefined || id.trim().length === 0) {
+        throw new InitiativeCliError('Pass an initiative id.', 'initiative_id_required', {
+            target: 'initiative.id',
+            fix: `openspec initiative ${commandName} <id>`,
+        });
+    }
+    return id.trim();
+}
+function toContextStoreOutput(selected) {
+    return {
+        id: selected.id,
+        root: selected.root,
+        source: selected.source,
+    };
+}
+function toInitiativeOutput(selected, state) {
+    const collection = mountInitiativesCollection(selected.root);
+    return {
+        ...state,
+        store: selected.id,
+        root: collection.resolvePath(state.id),
+        store_path: collection.toStorePath(state.id),
+    };
+}
+function listedInitiativeToOutput(initiative) {
+    return {
+        version: 1,
+        id: initiative.id,
+        title: initiative.title,
+        summary: initiative.summary,
+        status: initiative.status,
+        created: initiative.created,
+        owners: initiative.owners,
+        metadata: initiative.metadata,
+        store: initiative.store,
+        root: initiative.root,
+        store_path: initiative.storePath,
+    };
+}
+function initiativeReferenceToShowOutput(reference) {
+    return {
+        version: 1,
+        id: reference.id,
+        title: reference.title,
+        summary: reference.summary,
+        created: reference.created,
+        root: reference.root,
+        store_path: reference.storePath,
+        metadata_path: reference.metadataPath,
+    };
+}
+function printCreateHuman(payload) {
+    if (!payload.context_store || !payload.initiative) {
+        return;
+    }
+    console.log(chalk.green('Created initiative'));
+    console.log(`ID: ${payload.initiative.id}`);
+    console.log(`Title: ${payload.initiative.title}`);
+    console.log(`Status: ${payload.initiative.status}`);
+    console.log(`Context store: ${payload.context_store.id}`);
+    console.log(`Location: ${payload.initiative.root}`);
+    console.log('');
+    console.log(`Created files (${payload.created_files.length}):`);
+    for (const fileName of payload.created_files) {
+        console.log(`  - ${fileName}`);
+    }
+    console.log('');
+    console.log('Next useful commands:');
+    console.log(`  openspec initiative list ${formatContextStoreSelector(payload.context_store)}`);
+}
+function printTableHeader(includeStore) {
+    const idHeader = 'ID'.padEnd(22);
+    const storeHeader = includeStore ? `${'Store'.padEnd(12)}` : '';
+    console.log(`${idHeader}${storeHeader}Title`);
+}
+function printInitiativeRow(initiative, includeStore) {
+    const id = initiative.id.padEnd(22);
+    const store = includeStore ? `${initiative.store.padEnd(12)}` : '';
+    console.log(`${id}${store}${initiative.title}`);
+}
+function printListStatuses(statuses) {
+    if (statuses.length === 0) {
+        return;
+    }
+    console.log('');
+    for (const status of statuses) {
+        console.log(status.message);
+        if (status.fix) {
+            console.log(`Run: ${status.fix}`);
+        }
+    }
+}
+function printListHuman(payload) {
+    if (payload.context_store) {
+        console.log(`OpenSpec initiatives in ${payload.context_store.id} (${payload.initiatives.length})`);
+        if (payload.initiatives.length === 0) {
+            console.log('');
+            console.log(`No initiatives found in ${payload.context_store.id}.`);
+            console.log('');
+            console.log(`Location: ${payload.context_store.root}`);
+            return;
+        }
+        console.log('');
+        printTableHeader(false);
+        for (const initiative of payload.initiatives) {
+            printInitiativeRow(initiative, false);
+        }
+        console.log('');
+        console.log(`Location: ${payload.context_store.root}`);
+        return;
+    }
+    if (payload.context_stores.length === 0) {
+        console.log('No initiatives found because no context stores are registered.');
+        return;
+    }
+    if (payload.initiatives.length === 0) {
+        console.log('No initiatives found across registered context stores.');
+        printListStatuses(payload.status);
+        return;
+    }
+    console.log(`OpenSpec initiatives (${payload.initiatives.length} across ${payload.context_stores.length} stores)`);
+    console.log('');
+    printTableHeader(true);
+    for (const initiative of payload.initiatives) {
+        printInitiativeRow(initiative, true);
+    }
+    printListStatuses(payload.status);
+}
+function printShowHuman(payload) {
+    if (!payload.context_store || !payload.initiative) {
+        return;
+    }
+    console.log(`OpenSpec initiative: ${payload.initiative.title}`);
+    console.log('');
+    console.log(`ID: ${payload.initiative.id}`);
+    console.log(`Summary: ${payload.initiative.summary}`);
+    console.log(`Context store: ${payload.context_store.id}`);
+    console.log(`Location: ${payload.initiative.root}`);
+    console.log(`Metadata: ${payload.initiative.metadata_path}`);
+}
+function printDiagnosticMatches(diagnostic) {
+    const matches = diagnostic.details?.matches ?? [];
+    if (matches.length === 0) {
+        return;
+    }
+    console.error('');
+    console.error(diagnostic.code === 'initiative_lookup_incomplete' ? 'Partial matches:' : 'Matches:');
+    for (const match of matches) {
+        console.error(`  ${match.context_store.id.padEnd(12)}${match.initiative.root}`);
+    }
+}
+class InitiativeCommand {
+    async create(id, options = {}) {
+        try {
+            const initiativeId = requireInitiativeId(id, 'create');
+            const title = requireNonBlankOption(options.title, 'title', 'initiative.title', 'initiative_title_required');
+            const summary = requireNonBlankOption(options.summary, 'summary', 'initiative.summary', 'initiative_summary_required');
+            const selected = await selectContextStoreForInitiative(options, 'create');
+            const collection = mountInitiativesCollection(selected.root);
+            const state = await createInitiative({
+                collection,
+                id: initiativeId,
+                title,
+                summary,
+            });
+            const payload = {
+                context_store: toContextStoreOutput(selected),
+                initiative: toInitiativeOutput(selected, state),
+                created_files: [...INITIATIVE_FILE_NAMES],
+                status: [],
+            };
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            printCreateHuman(payload);
+        }
+        catch (error) {
+            this.handleFailure(options.json, { context_store: null, initiative: null, created_files: [], status: [] }, error);
+        }
+    }
+    async list(options = {}) {
+        try {
+            const payload = await this.buildListPayload(options);
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            printListHuman(payload);
+        }
+        catch (error) {
+            this.handleFailure(options.json, { context_store: null, context_stores: [], initiatives: [], status: [] }, error);
+        }
+    }
+    async show(id, options = {}) {
+        try {
+            const initiativeId = requireInitiativeId(id, 'show');
+            const payload = await this.buildShowPayload(initiativeId, options);
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            printShowHuman(payload);
+        }
+        catch (error) {
+            this.handleFailure(options.json, { context_store: null, initiative: null, status: [] }, error);
+        }
+    }
+    async buildListPayload(options) {
+        const listed = await listInitiativeViewReferences(options);
+        const contextStores = listed.contextStores.map((store) => ({
+            context_store: toContextStoreOutput(store.contextStore),
+            initiatives: store.initiatives.map(listedInitiativeToOutput),
+            status: store.status,
+        }));
+        return {
+            context_store: listed.contextStore ? toContextStoreOutput(listed.contextStore) : null,
+            context_stores: contextStores,
+            initiatives: listed.initiatives.map(listedInitiativeToOutput),
+            status: listed.status,
+        };
+    }
+    async buildShowPayload(initiativeId, options) {
+        const reference = await resolveCoreInitiativeViewReference(initiativeId, options);
+        return {
+            context_store: {
+                id: reference.store,
+                root: reference.storeRoot,
+            },
+            initiative: initiativeReferenceToShowOutput(reference),
+            status: [],
+        };
+    }
+    handleFailure(json, payload, error) {
+        const diagnostic = initiativeDiagnosticFromError(error);
+        if (json) {
+            printJson(appendDiagnostic(payload, diagnostic));
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`Error: ${diagnostic.message}`);
+        printDiagnosticMatches(diagnostic);
+        if (diagnostic.fix) {
+            console.error(`Fix: ${diagnostic.fix}`);
+        }
+        process.exitCode = 1;
+    }
+}
+function addContextStoreSelectorOptions(command) {
+    return command
+        .option('--store <id>', 'Context store id from the local context-store registry')
+        .option('--store-path <path>', 'Existing local context store root')
+        .option('--json', 'Output as JSON');
+}
+export function registerInitiativeCommand(program) {
+    const initiativeCommand = new InitiativeCommand();
+    const initiative = program
+        .command('initiative')
+        .description('Create and list coordinated initiatives');
+    addContextStoreSelectorOptions(initiative
+        .command('create [id]')
+        .description('Create an initiative in a context store')
+        .option('--title <title>', 'Initiative title')
+        .option('--summary <summary>', 'Initiative summary')).action(async (id, options) => {
+        await initiativeCommand.create(id, options);
+    });
+    addContextStoreSelectorOptions(initiative
+        .command('show <id>')
+        .description('Show where an initiative lives and how to read it')).action(async (id, options) => {
+        await initiativeCommand.show(id, options);
+    });
+    addContextStoreSelectorOptions(initiative
+        .command('list')
+        .alias('ls')
+        .description('List initiatives across registered context stores')).action(async (options) => {
+        await initiativeCommand.list(options);
+    });
+}
+//# sourceMappingURL=initiative.js.map

package/dist/commands/workflow/index.d.ts

@@ -13,5 +13,7 @@ export { schemasCommand } from './schemas.js';
 export type { SchemasOptions } from './schemas.js';
 export { newChangeCommand } from './new-change.js';
 export type { NewChangeOptions } from './new-change.js';
+export { setChangeCommand } from './set-change.js';
+export type { SetChangeOptions } from './set-change.js';
 export { DEFAULT_SCHEMA } from './shared.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/workflow/index.js

@@ -8,5 +8,6 @@ export { instructionsCommand, applyInstructionsCommand } from './instructions.js
 export { templatesCommand } from './templates.js';
 export { schemasCommand } from './schemas.js';
 export { newChangeCommand } from './new-change.js';
+export { setChangeCommand } from './set-change.js';
 export { DEFAULT_SCHEMA } from './shared.js';
 //# sourceMappingURL=index.js.map

package/dist/commands/workflow/initiative-link.d.ts

@@ -0,0 +1,24 @@
+import type { PlanningHome } from '../../core/planning-home.js';
+import { type InitiativeLinkReference } from '../../core/collections/initiatives/index.js';
+export interface ChangeCommandStatus {
+    severity: 'error' | 'warning';
+    code: string;
+    message: string;
+    target?: string;
+    fix?: string;
+    details?: unknown;
+}
+export interface InitiativeSelectorOptions {
+    initiative?: string;
+    store?: string;
+    storePath?: string;
+}
+export declare const REPO_LOCAL_INITIATIVE_LINK_ERROR = "Initiative links are supported only for repo-local changes. Run this command from the repo that owns the implementation plan.";
+export declare function printJson(payload: unknown): void;
+export declare function statusFromError(error: unknown): ChangeCommandStatus;
+export declare function assertInitiativeSelectorsHaveReference(options: InitiativeSelectorOptions): void;
+export declare function assertInitiativeReference(value: string | undefined): asserts value is string;
+export declare function assertRepoLocalInitiativeLinkPlanningHome(planningHome: PlanningHome): void;
+export declare function formatInitiativeLink(initiative: InitiativeLinkReference): string;
+export declare function sameInitiativeLink(left: InitiativeLinkReference | undefined, right: InitiativeLinkReference): boolean;
+//# sourceMappingURL=initiative-link.d.ts.map

package/dist/commands/workflow/initiative-link.js

@@ -0,0 +1,47 @@
+import { InitiativeResolutionError, } from '../../core/collections/initiatives/index.js';
+export const REPO_LOCAL_INITIATIVE_LINK_ERROR = 'Initiative links are supported only for repo-local changes. Run this command from the repo that owns the implementation plan.';
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function statusFromError(error) {
+    if (error instanceof InitiativeResolutionError) {
+        return {
+            severity: 'error',
+            code: error.code,
+            message: error.message,
+            ...(error.target ? { target: error.target } : {}),
+            ...(error.fix ? { fix: error.fix } : {}),
+            ...(error.details ? { details: error.details } : {}),
+        };
+    }
+    return {
+        severity: 'error',
+        code: 'change_error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+export function assertInitiativeSelectorsHaveReference(options) {
+    if (!options.initiative && (options.store !== undefined || options.storePath !== undefined)) {
+        throw new Error('Pass --initiative when using --store or --store-path.');
+    }
+    if (options.initiative !== undefined && options.initiative.trim().length === 0) {
+        throw new Error('Pass --initiative <id> to link a change to an initiative.');
+    }
+}
+export function assertInitiativeReference(value) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new Error('Pass --initiative <id> to set a change initiative link.');
+    }
+}
+export function assertRepoLocalInitiativeLinkPlanningHome(planningHome) {
+    if (planningHome.kind === 'workspace') {
+        throw new Error(REPO_LOCAL_INITIATIVE_LINK_ERROR);
+    }
+}
+export function formatInitiativeLink(initiative) {
+    return `${initiative.store}/${initiative.id}`;
+}
+export function sameInitiativeLink(left, right) {
+    return left?.store === right.store && left.id === right.id;
+}
+//# sourceMappingURL=initiative-link.js.map

package/dist/commands/workflow/instructions.js

@@ -54,10 +54,14 @@ export async function instructionsCommand(artifactId, options) {
     }
 }
 export function printInstructionsText(instructions, isBlocked) {
-    const { artifactId, changeName, schemaName, changeDir, resolvedOutputPath, description, instruction, context, rules, template, dependencies, unlocks, } = instructions;
+    const { artifactId, changeName, schemaName, changeDir, initiative, resolvedOutputPath, description, instruction, context, rules, template, dependencies, unlocks, } = instructions;
     // Opening tag
     console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
     console.log();
+    if (initiative) {
+        console.log(`<initiative store="${initiative.store}" id="${initiative.id}" />`);
+        console.log();
+    }
     // Warning for blocked artifacts
     if (isBlocked) {
         const missing = dependencies.filter((d) => !d.done).map((d) => d.id);
@@ -253,6 +257,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         changeName,
         changeDir,
         schemaName: context.schemaName,
+        ...(context.initiative ? { initiative: context.initiative } : {}),
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
@@ -286,9 +291,12 @@ export async function applyInstructionsCommand(options) {
     }
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+    const { changeName, schemaName, initiative, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
     console.log(`## Apply: ${changeName}`);
     console.log(`Schema: ${schemaName}`);
+    if (initiative) {
+        console.log(`Initiative: ${initiative.store}/${initiative.id}`);
+    }
     console.log();
     // Warning for blocked state
     if (state === 'blocked' && missingArtifacts) {

package/dist/commands/workflow/new-change.d.ts

@@ -8,6 +8,10 @@ export interface NewChangeOptions {
     goal?: string;
     areas?: string;
     schema?: string;
+    initiative?: string;
+    store?: string;
+    storePath?: string;
+    json?: boolean;
 }
 export declare function newChangeCommand(name: string | undefined, options: NewChangeOptions): Promise<void>;
 //# sourceMappingURL=new-change.d.ts.map

package/dist/commands/workflow/new-change.js

@@ -8,6 +8,8 @@ import path from 'path';
 import { createChange, validateChangeName } from '../../utils/change-utils.js';
 import { formatChangeLocation, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
 import { validateSchemaExists } from './shared.js';
+import { resolveInitiativeLinkReference, } from '../../core/collections/initiatives/index.js';
+import { assertInitiativeSelectorsHaveReference, assertRepoLocalInitiativeLinkPlanningHome, formatInitiativeLink, printJson, statusFromError, } from './initiative-link.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
 // -----------------------------------------------------------------------------
@@ -33,26 +35,60 @@ function validateWorkspaceAffectedAreas(planningHome, affectedAreas) {
             `Valid workspace link names: ${validMessage}`);
     }
 }
-export async function newChangeCommand(name, options) {
-    if (!name) {
-        throw new Error('Missing required argument <name>');
-    }
-    const validation = validateChangeName(name);
-    if (!validation.valid) {
-        throw new Error(validation.error);
+function outputForCreatedChange(id, changeDir, schema, initiative) {
+    return {
+        change: {
+            id,
+            path: changeDir,
+            metadataPath: path.join(changeDir, '.openspec.yaml'),
+            schema,
+        },
+        ...(initiative ? { initiative } : {}),
+    };
+}
+function printCreatedChangeHuman(payload, planningHome) {
+    if (!payload.change) {
+        return;
     }
-    const planningHome = resolveCurrentPlanningHomeSync();
-    const projectRoot = planningHome.root;
-    const affectedAreas = parseAffectedAreas(options.areas);
-    validateWorkspaceAffectedAreas(planningHome, affectedAreas);
-    // Validate schema if provided
-    if (options.schema) {
-        validateSchemaExists(options.schema, projectRoot);
+    const location = formatChangeLocation(planningHome, payload.change.id);
+    const scope = planningHome.kind === 'workspace' ? 'workspace change' : 'change';
+    console.log(`Created ${scope} '${payload.change.id}' at ${location}/`);
+    console.log(`Schema: ${payload.change.schema}`);
+    if (payload.initiative) {
+        console.log(`Initiative: ${formatInitiativeLink(payload.initiative)}`);
     }
-    const resolvedSchema = options.schema ?? planningHome.defaultSchema;
-    const schemaDisplay = ` with schema '${resolvedSchema}'`;
-    const spinner = ora(`Creating change '${name}'${schemaDisplay}...`).start();
+}
+export async function newChangeCommand(name, options) {
+    const spinner = options.json ? undefined : ora();
     try {
+        if (!name) {
+            throw new Error('Missing required argument <name>');
+        }
+        const validation = validateChangeName(name);
+        if (!validation.valid) {
+            throw new Error(validation.error);
+        }
+        assertInitiativeSelectorsHaveReference(options);
+        const planningHome = resolveCurrentPlanningHomeSync();
+        const projectRoot = planningHome.root;
+        const affectedAreas = parseAffectedAreas(options.areas);
+        validateWorkspaceAffectedAreas(planningHome, affectedAreas);
+        let initiative;
+        if (options.initiative !== undefined) {
+            assertRepoLocalInitiativeLinkPlanningHome(planningHome);
+            initiative = await resolveInitiativeLinkReference(options.initiative, {
+                store: options.store,
+                storePath: options.storePath,
+            });
+        }
+        // Validate schema if provided
+        if (options.schema) {
+            validateSchemaExists(options.schema, projectRoot);
+        }
+        const resolvedSchema = options.schema ?? planningHome.defaultSchema;
+        if (spinner) {
+            spinner.start(`Creating change '${name}' with schema '${resolvedSchema}'...`);
+        }
         const workspaceGoal = planningHome.kind === 'workspace'
             ? options.goal ?? options.description
             : options.goal;
@@ -63,6 +99,7 @@ export async function newChangeCommand(name, options) {
             metadata: {
                 ...(workspaceGoal ? { goal: workspaceGoal } : {}),
                 ...(affectedAreas.length > 0 ? { affected_areas: affectedAreas } : {}),
+                ...(initiative ? { initiative } : {}),
             },
         });
         // If description provided, create README.md with description
@@ -71,21 +108,33 @@ export async function newChangeCommand(name, options) {
             const readmePath = path.join(result.changeDir, 'README.md');
             await fs.writeFile(readmePath, `# ${name}\n\n${options.description}\n`, 'utf-8');
         }
-        const location = formatChangeLocation(planningHome, name);
-        const scope = planningHome.kind === 'workspace' ? 'workspace change' : 'change';
-        spinner.succeed(`Created ${scope} '${name}' at ${location}/ (schema: ${result.schema})`);
-        if (planningHome.kind === 'workspace') {
+        const payload = outputForCreatedChange(name, result.changeDir, result.schema, initiative);
+        if (options.json) {
+            printJson(payload);
+            return;
+        }
+        spinner?.stop();
+        printCreatedChangeHuman(payload, planningHome);
+        if (planningHome.kind === 'workspace' && !initiative) {
             if (affectedAreas.length > 0) {
                 console.log(`Affected areas: ${affectedAreas.join(', ')}`);
             }
             else {
-                console.log('Affected areas: unresolved; identify them in workspace specs or tasks as planning continues.');
+                console.log('Affected areas: unresolved; identify them in change metadata or coordination tasks as planning continues.');
             }
             console.log('Next: run openspec status --change "' + name + '" to inspect workspace planning artifacts.');
         }
     }
     catch (error) {
-        spinner.fail(`Failed to create change '${name}'`);
+        spinner?.stop();
+        if (options.json) {
+            printJson({
+                change: null,
+                status: [statusFromError(error)],
+            });
+            process.exitCode = 1;
+            return;
+        }
         throw error;
     }
 }

package/dist/commands/workflow/set-change.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Set Change Command
+ *
+ * Mutates checked-in repo-local change metadata.
+ */
+export interface SetChangeOptions {
+    initiative?: string;
+    store?: string;
+    storePath?: string;
+    json?: boolean;
+}
+export declare function setChangeCommand(name: string | undefined, options: SetChangeOptions): Promise<void>;
+//# sourceMappingURL=set-change.d.ts.map