@fission-ai/openspec 1.3.0 → 1.4.0

package/dist/core/collections/initiatives/schema.js

@@ -0,0 +1,134 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+export const INITIATIVE_COLLECTION_ID = 'initiatives';
+export const INITIATIVE_FILE_NAME = 'initiative.yaml';
+export const INITIATIVE_REQUIREMENTS_FILE_NAME = 'requirements.md';
+export const INITIATIVE_DESIGN_FILE_NAME = 'design.md';
+export const INITIATIVE_DECISIONS_FILE_NAME = 'decisions.md';
+export const INITIATIVE_QUESTIONS_FILE_NAME = 'questions.md';
+export const INITIATIVE_TASKS_FILE_NAME = 'tasks.md';
+export const INITIATIVE_MARKDOWN_FILE_NAMES = [
+    INITIATIVE_REQUIREMENTS_FILE_NAME,
+    INITIATIVE_DESIGN_FILE_NAME,
+    INITIATIVE_DECISIONS_FILE_NAME,
+    INITIATIVE_QUESTIONS_FILE_NAME,
+    INITIATIVE_TASKS_FILE_NAME,
+];
+export const INITIATIVE_FILE_NAMES = [
+    INITIATIVE_FILE_NAME,
+    ...INITIATIVE_MARKDOWN_FILE_NAMES,
+];
+export const INITIATIVE_STATUSES = [
+    'exploring',
+    'active',
+    'complete',
+    'archived',
+];
+const INITIATIVE_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+function assertNoNul(value, label) {
+    if (value.includes('\0')) {
+        throw new Error(`${label} must not contain NUL bytes`);
+    }
+}
+function nonBlankString(label) {
+    return z.string().refine((value) => value.trim().length > 0, {
+        message: `${label} must not be empty`,
+    });
+}
+const InitiativeMetadataValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(InitiativeMetadataValueSchema),
+    z.record(z.string(), InitiativeMetadataValueSchema),
+]));
+const InitiativeMetadataSchema = z.record(z.string(), InitiativeMetadataValueSchema);
+const InitiativeStateSchema = z.object({
+    version: z.literal(1),
+    id: z.string(),
+    title: nonBlankString('title'),
+    summary: nonBlankString('summary'),
+    status: z.enum(INITIATIVE_STATUSES),
+    created: z.string().regex(INITIATIVE_DATE_PATTERN, {
+        message: 'created must be YYYY-MM-DD format',
+    }),
+    owners: z.array(nonBlankString('owner')).default([]),
+    metadata: InitiativeMetadataSchema.default({}),
+}).strict();
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const location = issue.path.length > 0 ? issue.path.join('.') : 'root';
+        return `${location}: ${issue.message}`;
+    })
+        .join('; ');
+}
+function parseYamlObject(content, label) {
+    try {
+        return parseYaml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${label}: ${message}`);
+    }
+}
+export function validateInitiativeId(id) {
+    assertNoNul(id, 'Initiative id');
+    if (id.length === 0) {
+        throw new Error('Initiative id must not be empty');
+    }
+    if (id === '.' || id === '..') {
+        throw new Error(`Initiative id must not be '${id}'`);
+    }
+    if (/[\\/]/u.test(id)) {
+        throw new Error('Initiative id must not contain path separators');
+    }
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(id)) {
+        throw new Error('Initiative id must be kebab-case with lowercase letters, numbers, and single hyphen separators');
+    }
+    return id;
+}
+export function isValidInitiativeId(id) {
+    try {
+        validateInitiativeId(id);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseInitiativeStateInput(raw) {
+    const result = InitiativeStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid initiative state: ${formatZodIssues(result.error)}`);
+    }
+    validateInitiativeId(result.data.id);
+    return {
+        version: 1,
+        id: result.data.id,
+        title: result.data.title,
+        summary: result.data.summary,
+        status: result.data.status,
+        created: result.data.created,
+        owners: result.data.owners,
+        metadata: result.data.metadata,
+    };
+}
+export function parseInitiativeState(content) {
+    return parseInitiativeStateInput(parseYamlObject(content, 'initiative state'));
+}
+export function serializeInitiativeState(state) {
+    const parsedState = parseInitiativeStateInput(state);
+    return stringifyYaml({
+        version: 1,
+        id: parsedState.id,
+        title: parsedState.title,
+        summary: parsedState.summary,
+        status: parsedState.status,
+        created: parsedState.created,
+        owners: parsedState.owners,
+        metadata: parsedState.metadata,
+    });
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/collections/initiatives/templates.d.ts

@@ -0,0 +1,12 @@
+import { type InitiativeMarkdownFileName, type InitiativeState } from './schema.js';
+export interface InitiativeTemplateFile {
+    fileName: InitiativeMarkdownFileName;
+    content: string;
+}
+export declare function buildInitiativeRequirementsTemplate(state: InitiativeState): string;
+export declare function buildInitiativeDesignTemplate(state: InitiativeState): string;
+export declare function buildInitiativeDecisionsTemplate(state: InitiativeState): string;
+export declare function buildInitiativeQuestionsTemplate(): string;
+export declare function buildInitiativeTasksTemplate(): string;
+export declare function buildDefaultInitiativeFiles(state: InitiativeState): InitiativeTemplateFile[];
+//# sourceMappingURL=templates.d.ts.map

package/dist/core/collections/initiatives/templates.js

@@ -0,0 +1,90 @@
+import { INITIATIVE_DECISIONS_FILE_NAME, INITIATIVE_DESIGN_FILE_NAME, INITIATIVE_MARKDOWN_FILE_NAMES, INITIATIVE_QUESTIONS_FILE_NAME, INITIATIVE_REQUIREMENTS_FILE_NAME, INITIATIVE_TASKS_FILE_NAME, } from './schema.js';
+function withTrailingNewline(content) {
+    return content.endsWith('\n') ? content : `${content}\n`;
+}
+export function buildInitiativeRequirementsTemplate(state) {
+    return withTrailingNewline(`# Requirements
+
+## Product Intent
+
+${state.summary}
+
+## Accepted Requirements
+
+- TBD
+
+## Out Of Scope
+
+- TBD
+`);
+}
+export function buildInitiativeDesignTemplate(state) {
+    return withTrailingNewline(`# Design
+
+## Context
+
+${state.summary}
+
+## Approach
+
+TBD
+
+## Affected Areas
+
+- TBD
+
+## Dependencies
+
+- TBD
+
+## Risks
+
+- TBD
+`);
+}
+export function buildInitiativeDecisionsTemplate(state) {
+    return withTrailingNewline(`# Decisions
+
+## Accepted Decisions
+
+### ${state.created}: ${state.title}
+
+- Decision: TBD
+- Why: TBD
+- Implications: TBD
+`);
+}
+export function buildInitiativeQuestionsTemplate() {
+    return withTrailingNewline(`# Questions
+
+## Open Questions
+
+- TBD
+
+## Resolved Questions
+
+- TBD
+`);
+}
+export function buildInitiativeTasksTemplate() {
+    return withTrailingNewline(`# Tasks
+
+## Coordination Tasks
+
+- [ ] TBD
+`);
+}
+export function buildDefaultInitiativeFiles(state) {
+    const templates = {
+        [INITIATIVE_REQUIREMENTS_FILE_NAME]: buildInitiativeRequirementsTemplate(state),
+        [INITIATIVE_DESIGN_FILE_NAME]: buildInitiativeDesignTemplate(state),
+        [INITIATIVE_DECISIONS_FILE_NAME]: buildInitiativeDecisionsTemplate(state),
+        [INITIATIVE_QUESTIONS_FILE_NAME]: buildInitiativeQuestionsTemplate(),
+        [INITIATIVE_TASKS_FILE_NAME]: buildInitiativeTasksTemplate(),
+    };
+    return INITIATIVE_MARKDOWN_FILE_NAMES.map((fileName) => ({
+        fileName,
+        content: templates[fileName],
+    }));
+}
+//# sourceMappingURL=templates.js.map

package/dist/core/collections/runtime.d.ts

@@ -0,0 +1,46 @@
+export type CollectionMetadata = Readonly<Record<string, unknown>>;
+export type CollectionHooks = Readonly<Record<string, unknown>>;
+export interface CollectionDefinition<THandle = unknown> {
+    id: string;
+    mount: string;
+    metadata?: CollectionMetadata;
+    hooks?: CollectionHooks;
+    createHandle?: (context: MountedCollectionContext) => THandle;
+}
+export interface CollectionRegistry {
+    list(): readonly CollectionDefinition[];
+    get<THandle = unknown>(collectionId: string): CollectionDefinition<THandle> | undefined;
+    require<THandle = unknown>(collectionId: string): CollectionDefinition<THandle>;
+}
+export interface MountedCollectionContext {
+    storeRoot: string;
+    collectionId: string;
+    mount: string;
+    mountRoot: string;
+    resolvePath(relativePath?: string): string;
+    toStorePath(relativePath?: string): string;
+}
+export interface MountedCollection<THandle = unknown> {
+    collectionId: string;
+    mount: string;
+    mountRoot: string;
+    context: MountedCollectionContext;
+    handle: THandle | undefined;
+    resolvePath(relativePath?: string): string;
+    toStorePath(relativePath?: string): string;
+}
+export interface MountedCollectionRegistry {
+    list(): readonly MountedCollection[];
+    get<THandle = unknown>(collectionId: string): MountedCollection<THandle> | undefined;
+    require<THandle = unknown>(collectionId: string): MountedCollection<THandle>;
+}
+export interface MountCollectionsInput {
+    storeRoot: string;
+    collections: CollectionRegistry;
+}
+export declare function validateCollectionId(id: string): string;
+export declare function validateMount(mount: string): string;
+export declare function parseCollectionPath(input?: string): string;
+export declare function createCollectionRegistry(definitions: readonly CollectionDefinition[]): CollectionRegistry;
+export declare function mountCollections(input: MountCollectionsInput): MountedCollectionRegistry;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/core/collections/runtime.js

@@ -0,0 +1,194 @@
+import * as path from 'node:path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+function assertNoNul(value, label) {
+    if (value.includes('\0')) {
+        throw new Error(`${label} must not contain NUL bytes`);
+    }
+}
+function validateKebabSegment(value, label) {
+    assertNoNul(value, label);
+    if (value.length === 0) {
+        throw new Error(`${label} must not be empty`);
+    }
+    if (value === '.' || value === '..') {
+        throw new Error(`${label} must not be '${value}'`);
+    }
+    if (/[\\/]/u.test(value)) {
+        throw new Error(`${label} must not contain path separators`);
+    }
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value)) {
+        throw new Error(`${label} must be kebab-case with lowercase letters, numbers, and single hyphen separators`);
+    }
+    return value;
+}
+export function validateCollectionId(id) {
+    return validateKebabSegment(id, 'Collection id');
+}
+export function validateMount(mount) {
+    assertNoNul(mount, 'Collection mount');
+    if (mount.startsWith('.')) {
+        throw new Error(`Collection mount '${mount}' is reserved`);
+    }
+    return validateKebabSegment(mount, 'Collection mount');
+}
+function isWindowsDrivePath(value) {
+    return /^[A-Za-z]:/u.test(value);
+}
+function isUncPath(value) {
+    return value.startsWith('\\\\') || value.startsWith('//');
+}
+export function parseCollectionPath(input = '') {
+    assertNoNul(input, 'Collection path');
+    if (input.length === 0) {
+        return '';
+    }
+    if (input.includes('\\')) {
+        throw new Error('Collection path must use forward slashes');
+    }
+    if (isWindowsDrivePath(input)) {
+        throw new Error('Collection path must not be a Windows drive path');
+    }
+    if (isUncPath(input) || path.posix.isAbsolute(input)) {
+        throw new Error('Collection path must be relative');
+    }
+    const segments = input.split('/');
+    for (const segment of segments) {
+        if (segment.length === 0) {
+            throw new Error('Collection path must not contain empty segments');
+        }
+        if (segment === '.' || segment === '..') {
+            throw new Error('Collection path must not contain dot segments');
+        }
+    }
+    return segments.join('/');
+}
+function compareCollectionDefinitions(a, b) {
+    return a.id.localeCompare(b.id);
+}
+export function createCollectionRegistry(definitions) {
+    const byId = new Map();
+    const mountOwners = new Map();
+    for (const definition of definitions) {
+        const id = validateCollectionId(definition.id);
+        const mount = validateMount(definition.mount);
+        if (byId.has(id)) {
+            throw new Error(`Duplicate collection id '${id}'`);
+        }
+        const existingMountOwner = mountOwners.get(mount);
+        if (existingMountOwner) {
+            throw new Error(`Duplicate collection mount '${mount}' for '${existingMountOwner}' and '${id}'`);
+        }
+        const normalizedDefinition = {
+            ...definition,
+            id,
+            mount,
+        };
+        byId.set(id, normalizedDefinition);
+        mountOwners.set(mount, id);
+    }
+    const sortedDefinitions = Array.from(byId.values()).sort(compareCollectionDefinitions);
+    return {
+        list() {
+            return [...sortedDefinitions];
+        },
+        get(collectionId) {
+            const id = validateCollectionId(collectionId);
+            return byId.get(id);
+        },
+        require(collectionId) {
+            const definition = this.get(collectionId);
+            if (!definition) {
+                throw new Error(`Unknown collection '${collectionId}'`);
+            }
+            return definition;
+        },
+    };
+}
+function isWindowsLikePath(candidatePath) {
+    return /^[A-Za-z]:[\\/]/u.test(candidatePath) || candidatePath.startsWith('\\\\');
+}
+function relativePath(fromPath, toPath) {
+    if (isWindowsLikePath(fromPath) || isWindowsLikePath(toPath)) {
+        return path.win32.relative(path.win32.normalize(fromPath), path.win32.normalize(toPath));
+    }
+    return path.posix.relative(fromPath.replace(/\\/g, '/'), toPath.replace(/\\/g, '/'));
+}
+function isRelativePathAbsolute(value, windowsLike) {
+    return windowsLike ? path.win32.isAbsolute(value) : path.posix.isAbsolute(value);
+}
+function isSameOrDescendant(rootPath, candidatePath) {
+    const windowsLike = isWindowsLikePath(rootPath) || isWindowsLikePath(candidatePath);
+    const relative = relativePath(rootPath, candidatePath);
+    const escapesRoot = /^\.\.(?:[\\/]|$)/u.test(relative);
+    return (relative === '' ||
+        (!escapesRoot && !isRelativePathAbsolute(relative, windowsLike)));
+}
+function getMountRoot(storeRoot, mount) {
+    return FileSystemUtils.joinPath(storeRoot, validateMount(mount));
+}
+function resolvePathInsideMount(mountRoot, relativePath) {
+    const collectionPath = parseCollectionPath(relativePath);
+    const resolvedPath = collectionPath.length > 0
+        ? FileSystemUtils.joinPath(mountRoot, collectionPath)
+        : mountRoot;
+    if (!isSameOrDescendant(mountRoot, resolvedPath)) {
+        throw new Error(`Collection path escapes mount: ${relativePath ?? ''}`);
+    }
+    return resolvedPath;
+}
+function toStorePath(mount, relativePath) {
+    const collectionPath = parseCollectionPath(relativePath);
+    return collectionPath.length > 0
+        ? `${validateMount(mount)}/${collectionPath}`
+        : validateMount(mount);
+}
+function createMountedCollection(storeRoot, definition) {
+    const mountRoot = getMountRoot(storeRoot, definition.mount);
+    const resolveMountedPath = (relativePath) => resolvePathInsideMount(mountRoot, relativePath);
+    const resolveStorePath = (relativePath) => toStorePath(definition.mount, relativePath);
+    const context = {
+        storeRoot,
+        collectionId: definition.id,
+        mount: definition.mount,
+        mountRoot,
+        resolvePath: resolveMountedPath,
+        toStorePath: resolveStorePath,
+    };
+    return {
+        collectionId: definition.id,
+        mount: definition.mount,
+        mountRoot,
+        context,
+        handle: definition.createHandle?.(context),
+        resolvePath: resolveMountedPath,
+        toStorePath: resolveStorePath,
+    };
+}
+export function mountCollections(input) {
+    if (input.storeRoot.length === 0) {
+        throw new Error('Context store root must not be empty');
+    }
+    const byId = new Map();
+    for (const definition of input.collections.list()) {
+        const mountedCollection = createMountedCollection(input.storeRoot, definition);
+        byId.set(mountedCollection.collectionId, mountedCollection);
+    }
+    const sortedCollections = Array.from(byId.values()).sort((a, b) => a.collectionId.localeCompare(b.collectionId));
+    return {
+        list() {
+            return [...sortedCollections];
+        },
+        get(collectionId) {
+            const id = validateCollectionId(collectionId);
+            return byId.get(id);
+        },
+        require(collectionId) {
+            const mountedCollection = this.get(collectionId);
+            if (!mountedCollection) {
+                throw new Error(`Unknown mounted collection '${collectionId}'`);
+            }
+            return mountedCollection;
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/core/completions/command-registry.d.ts

@@ -1,7 +1,3 @@
-import { CommandDefinition } from './types.js';
-/**
- * Registry of all OpenSpec CLI commands with their flags and metadata.
- * This registry is used to generate shell completion scripts.
- */
+import type { CommandDefinition } from './types.js';
 export declare const COMMAND_REGISTRY: CommandDefinition[];
 //# sourceMappingURL=command-registry.d.ts.map