@zhuan-ai/zhuanspec 1.3.0

package/dist/core/artifact-graph/state.js

@@ -0,0 +1,54 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import { FileSystemUtils } from '../../utils/file-system.js';
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ * Returns a Set of completed artifact IDs.
+ *
+ * @param graph - The artifact graph to check
+ * @param changeDir - The change directory to scan for files
+ * @returns Set of artifact IDs whose generated files exist
+ */
+export function detectCompleted(graph, changeDir) {
+    const completed = new Set();
+    // Handle missing change directory gracefully
+    if (!fs.existsSync(changeDir)) {
+        return completed;
+    }
+    for (const artifact of graph.getAllArtifacts()) {
+        if (isArtifactComplete(artifact.generates, changeDir)) {
+            completed.add(artifact.id);
+        }
+    }
+    return completed;
+}
+/**
+ * Checks if an artifact is complete by checking if its generated file(s) exist.
+ * Supports both simple paths and glob patterns.
+ */
+function isArtifactComplete(generates, changeDir) {
+    const fullPattern = path.join(changeDir, generates);
+    // Check if it's a glob pattern
+    if (isGlobPattern(generates)) {
+        return hasGlobMatches(fullPattern);
+    }
+    // Simple file path - check if file exists
+    return fs.existsSync(fullPattern);
+}
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+function isGlobPattern(pattern) {
+    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+}
+/**
+ * Checks if a glob pattern has any matches.
+ * Normalizes Windows backslashes to forward slashes for cross-platform glob compatibility.
+ */
+function hasGlobMatches(pattern) {
+    const normalizedPattern = FileSystemUtils.toPosixPath(pattern);
+    const matches = fg.sync(normalizedPattern, { onlyFiles: true });
+    return matches.length > 0;
+}
+//# sourceMappingURL=state.js.map

package/dist/core/artifact-graph/types.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export declare const ArtifactSchema: z.ZodObject<{
+    id: z.ZodString;
+    generates: z.ZodString;
+    description: z.ZodString;
+    template: z.ZodString;
+    instruction: z.ZodOptional<z.ZodString>;
+    requires: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const ApplyPhaseSchema: z.ZodObject<{
+    requires: z.ZodArray<z.ZodString>;
+    tracks: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    instruction: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SchemaYamlSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        generates: z.ZodString;
+        description: z.ZodString;
+        template: z.ZodString;
+        instruction: z.ZodOptional<z.ZodString>;
+        requires: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    apply: z.ZodOptional<z.ZodObject<{
+        requires: z.ZodArray<z.ZodString>;
+        tracks: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        instruction: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Artifact = z.infer<typeof ArtifactSchema>;
+export type ApplyPhase = z.infer<typeof ApplyPhaseSchema>;
+export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+export declare const ChangeMetadataSchema: z.ZodObject<{
+    schema: z.ZodString;
+    created: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
+export type CompletedSet = Set<string>;
+export interface BlockedArtifacts {
+    [artifactId: string]: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/artifact-graph/types.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+// Artifact definition schema
+export const ArtifactSchema = z.object({
+    id: z.string().min(1, { error: 'Artifact ID is required' }),
+    generates: z.string().min(1, { error: 'generates field is required' }),
+    description: z.string(),
+    template: z.string().min(1, { error: 'template field is required' }),
+    instruction: z.string().optional(),
+    requires: z.array(z.string()).default([]),
+});
+// Apply phase configuration for schema-aware apply instructions
+export const ApplyPhaseSchema = z.object({
+    // Artifact IDs that must exist before apply is available
+    requires: z.array(z.string()).min(1, { error: 'At least one required artifact' }),
+    // Path to file with checkboxes for progress (relative to change dir), or null if no tracking
+    tracks: z.string().nullable().optional(),
+    // Custom guidance for the apply phase
+    instruction: z.string().optional(),
+});
+// Full schema YAML structure
+export const SchemaYamlSchema = z.object({
+    name: z.string().min(1, { error: 'Schema name is required' }),
+    version: z.number().int().positive({ error: 'Version must be a positive integer' }),
+    description: z.string().optional(),
+    artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+    // Optional apply phase configuration (for schema-aware apply instructions)
+    apply: ApplyPhaseSchema.optional(),
+});
+// Per-change metadata schema
+// Note: schema field is validated at parse time against available schemas
+// using a lazy import to avoid circular dependencies
+export const ChangeMetadataSchema = z.object({
+    // Required: which workflow schema this change uses
+    schema: z.string().min(1, { message: 'schema is required' }),
+    // Optional: creation timestamp (ISO date string)
+    created: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, {
+        message: 'created must be YYYY-MM-DD format',
+    })
+        .optional(),
+});
+//# sourceMappingURL=types.js.map

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

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

package/dist/core/completions/command-registry.js

@@ -0,0 +1,362 @@
+/**
+ * Common flags used across multiple commands
+ */
+const COMMON_FLAGS = {
+    json: {
+        name: 'json',
+        description: 'Output as JSON',
+    },
+    jsonValidation: {
+        name: 'json',
+        description: 'Output validation results as JSON',
+    },
+    strict: {
+        name: 'strict',
+        description: 'Enable strict validation mode',
+    },
+    noInteractive: {
+        name: 'no-interactive',
+        description: 'Disable interactive prompts',
+    },
+    type: {
+        name: 'type',
+        description: 'Specify item type when ambiguous',
+        takesValue: true,
+        values: ['change', 'spec'],
+    },
+};
+/**
+ * Registry of all ZhuanSpec CLI commands with their flags and metadata.
+ * This registry is used to generate shell completion scripts.
+ */
+export const COMMAND_REGISTRY = [
+    {
+        name: 'init',
+        description: 'Initialize ZhuanSpec in your project',
+        acceptsPositional: true,
+        positionalType: 'path',
+        flags: [
+            {
+                name: 'tools',
+                description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: 'update',
+        description: 'Update ZhuanSpec instruction files',
+        acceptsPositional: true,
+        positionalType: 'path',
+        flags: [],
+    },
+    {
+        name: 'list',
+        description: 'List items (changes by default, or specs with --specs)',
+        flags: [
+            {
+                name: 'specs',
+                description: 'List specs instead of changes',
+            },
+            {
+                name: 'changes',
+                description: 'List changes explicitly (default)',
+            },
+        ],
+    },
+    {
+        name: 'view',
+        description: 'Display an interactive dashboard of specs and changes',
+        flags: [],
+    },
+    {
+        name: 'validate',
+        description: 'Validate changes and specs',
+        acceptsPositional: true,
+        positionalType: 'change-or-spec-id',
+        flags: [
+            {
+                name: 'all',
+                description: 'Validate all changes and specs',
+            },
+            {
+                name: 'changes',
+                description: 'Validate all changes',
+            },
+            {
+                name: 'specs',
+                description: 'Validate all specs',
+            },
+            COMMON_FLAGS.type,
+            COMMON_FLAGS.strict,
+            COMMON_FLAGS.jsonValidation,
+            {
+                name: 'concurrency',
+                description: 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)',
+                takesValue: true,
+            },
+            COMMON_FLAGS.noInteractive,
+        ],
+    },
+    {
+        name: 'show',
+        description: 'Show a change or spec',
+        acceptsPositional: true,
+        positionalType: 'change-or-spec-id',
+        flags: [
+            COMMON_FLAGS.json,
+            COMMON_FLAGS.type,
+            COMMON_FLAGS.noInteractive,
+            {
+                name: 'deltas-only',
+                description: 'Show only deltas (JSON only, change-specific)',
+            },
+            {
+                name: 'requirements-only',
+                description: 'Alias for --deltas-only (deprecated, change-specific)',
+            },
+            {
+                name: 'requirements',
+                description: 'Show only requirements, exclude scenarios (JSON only, spec-specific)',
+            },
+            {
+                name: 'no-scenarios',
+                description: 'Exclude scenario content (JSON only, spec-specific)',
+            },
+            {
+                name: 'requirement',
+                short: 'r',
+                description: 'Show specific requirement by ID (JSON only, spec-specific)',
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: 'archive',
+        description: 'Archive a completed change and update main specs',
+        acceptsPositional: true,
+        positionalType: 'change-id',
+        flags: [
+            {
+                name: 'yes',
+                short: 'y',
+                description: 'Skip confirmation prompts',
+            },
+            {
+                name: 'skip-specs',
+                description: 'Skip spec update operations',
+            },
+            {
+                name: 'no-validate',
+                description: 'Skip validation (not recommended)',
+            },
+        ],
+    },
+    {
+        name: 'change',
+        description: 'Manage ZhuanSpec change proposals (deprecated)',
+        flags: [],
+        subcommands: [
+            {
+                name: 'show',
+                description: 'Show a change proposal',
+                acceptsPositional: true,
+                positionalType: 'change-id',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'deltas-only',
+                        description: 'Show only deltas (JSON only)',
+                    },
+                    {
+                        name: 'requirements-only',
+                        description: 'Alias for --deltas-only (deprecated)',
+                    },
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+            {
+                name: 'list',
+                description: 'List all active changes (deprecated)',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'long',
+                        description: 'Show id and title with counts',
+                    },
+                ],
+            },
+            {
+                name: 'validate',
+                description: 'Validate a change proposal',
+                acceptsPositional: true,
+                positionalType: 'change-id',
+                flags: [
+                    COMMON_FLAGS.strict,
+                    COMMON_FLAGS.jsonValidation,
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'spec',
+        description: 'Manage ZhuanSpec specifications',
+        flags: [],
+        subcommands: [
+            {
+                name: 'show',
+                description: 'Show a specification',
+                acceptsPositional: true,
+                positionalType: 'spec-id',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'requirements',
+                        description: 'Show only requirements, exclude scenarios (JSON only)',
+                    },
+                    {
+                        name: 'no-scenarios',
+                        description: 'Exclude scenario content (JSON only)',
+                    },
+                    {
+                        name: 'requirement',
+                        short: 'r',
+                        description: 'Show specific requirement by ID (JSON only)',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+            {
+                name: 'list',
+                description: 'List all specifications',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'long',
+                        description: 'Show id and title with counts',
+                    },
+                ],
+            },
+            {
+                name: 'validate',
+                description: 'Validate a specification',
+                acceptsPositional: true,
+                positionalType: 'spec-id',
+                flags: [
+                    COMMON_FLAGS.strict,
+                    COMMON_FLAGS.jsonValidation,
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'completion',
+        description: 'Manage shell completions for ZhuanSpec CLI',
+        flags: [],
+        subcommands: [
+            {
+                name: 'generate',
+                description: 'Generate completion script for a shell (outputs to stdout)',
+                acceptsPositional: true,
+                positionalType: 'shell',
+                flags: [],
+            },
+            {
+                name: 'install',
+                description: 'Install completion script for a shell',
+                acceptsPositional: true,
+                positionalType: 'shell',
+                flags: [
+                    {
+                        name: 'verbose',
+                        description: 'Show detailed installation output',
+                    },
+                ],
+            },
+            {
+                name: 'uninstall',
+                description: 'Uninstall completion script for a shell',
+                acceptsPositional: true,
+                positionalType: 'shell',
+                flags: [],
+            },
+        ],
+    },
+    {
+        name: 'config',
+        description: 'View and modify global ZhuanSpec configuration',
+        flags: [
+            {
+                name: 'scope',
+                description: 'Config scope (only "global" supported currently)',
+                takesValue: true,
+                values: ['global'],
+            },
+        ],
+        subcommands: [
+            {
+                name: 'path',
+                description: 'Show config file location',
+                flags: [],
+            },
+            {
+                name: 'list',
+                description: 'Show all current settings',
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'get',
+                description: 'Get a specific value (raw, scriptable)',
+                acceptsPositional: true,
+                flags: [],
+            },
+            {
+                name: 'set',
+                description: 'Set a value (auto-coerce types)',
+                acceptsPositional: true,
+                flags: [
+                    {
+                        name: 'string',
+                        description: 'Force value to be stored as string',
+                    },
+                    {
+                        name: 'allow-unknown',
+                        description: 'Allow setting unknown keys',
+                    },
+                ],
+            },
+            {
+                name: 'unset',
+                description: 'Remove a key (revert to default)',
+                acceptsPositional: true,
+                flags: [],
+            },
+            {
+                name: 'reset',
+                description: 'Reset configuration to defaults',
+                flags: [
+                    {
+                        name: 'all',
+                        description: 'Reset all configuration (required)',
+                    },
+                    {
+                        name: 'yes',
+                        short: 'y',
+                        description: 'Skip confirmation prompts',
+                    },
+                ],
+            },
+            {
+                name: 'edit',
+                description: 'Open config in $EDITOR',
+                flags: [],
+            },
+        ],
+    },
+];
+//# sourceMappingURL=command-registry.js.map

package/dist/core/completions/completion-provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Provides dynamic completion suggestions for ZhuanSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export declare class CompletionProvider {
+    private readonly cacheTTLMs;
+    private readonly projectRoot;
+    private readonly cacheTTL;
+    private changeCache;
+    private specCache;
+    /**
+     * Creates a new completion provider
+     *
+     * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(cacheTTLMs?: number, projectRoot?: string);
+    /**
+     * Get all active change IDs for completion
+     *
+     * @returns Array of change IDs
+     */
+    getChangeIds(): Promise<string[]>;
+    /**
+     * Get all spec IDs for completion
+     *
+     * @returns Array of spec IDs
+     */
+    getSpecIds(): Promise<string[]>;
+    /**
+     * Get both change and spec IDs for completion
+     *
+     * @returns Object with changeIds and specIds arrays
+     */
+    getAllIds(): Promise<{
+        changeIds: string[];
+        specIds: string[];
+    }>;
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Cache status information
+     */
+    getCacheStats(): {
+        changeCache: {
+            valid: boolean;
+            age?: number;
+        };
+        specCache: {
+            valid: boolean;
+            age?: number;
+        };
+    };
+}
+//# sourceMappingURL=completion-provider.d.ts.map

package/dist/core/completions/completion-provider.js

@@ -0,0 +1,102 @@
+import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
+/**
+ * Provides dynamic completion suggestions for ZhuanSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export class CompletionProvider {
+    cacheTTLMs;
+    projectRoot;
+    cacheTTL;
+    changeCache = null;
+    specCache = null;
+    /**
+     * Creates a new completion provider
+     *
+     * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(cacheTTLMs = 2000, projectRoot = process.cwd()) {
+        this.cacheTTLMs = cacheTTLMs;
+        this.projectRoot = projectRoot;
+        this.cacheTTL = cacheTTLMs;
+    }
+    /**
+     * Get all active change IDs for completion
+     *
+     * @returns Array of change IDs
+     */
+    async getChangeIds() {
+        const now = Date.now();
+        // Check if cache is valid
+        if (this.changeCache && now - this.changeCache.timestamp < this.cacheTTL) {
+            return this.changeCache.data;
+        }
+        // Fetch fresh data
+        const changeIds = await getActiveChangeIds(this.projectRoot);
+        // Update cache
+        this.changeCache = {
+            data: changeIds,
+            timestamp: now,
+        };
+        return changeIds;
+    }
+    /**
+     * Get all spec IDs for completion
+     *
+     * @returns Array of spec IDs
+     */
+    async getSpecIds() {
+        const now = Date.now();
+        // Check if cache is valid
+        if (this.specCache && now - this.specCache.timestamp < this.cacheTTL) {
+            return this.specCache.data;
+        }
+        // Fetch fresh data
+        const specIds = await getSpecIds(this.projectRoot);
+        // Update cache
+        this.specCache = {
+            data: specIds,
+            timestamp: now,
+        };
+        return specIds;
+    }
+    /**
+     * Get both change and spec IDs for completion
+     *
+     * @returns Object with changeIds and specIds arrays
+     */
+    async getAllIds() {
+        const [changeIds, specIds] = await Promise.all([
+            this.getChangeIds(),
+            this.getSpecIds(),
+        ]);
+        return { changeIds, specIds };
+    }
+    /**
+     * Clear all cached data
+     */
+    clearCache() {
+        this.changeCache = null;
+        this.specCache = null;
+    }
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Cache status information
+     */
+    getCacheStats() {
+        const now = Date.now();
+        return {
+            changeCache: {
+                valid: this.changeCache !== null && now - this.changeCache.timestamp < this.cacheTTL,
+                age: this.changeCache ? now - this.changeCache.timestamp : undefined,
+            },
+            specCache: {
+                valid: this.specCache !== null && now - this.specCache.timestamp < this.cacheTTL,
+                age: this.specCache ? now - this.specCache.timestamp : undefined,
+            },
+        };
+    }
+}
+//# sourceMappingURL=completion-provider.js.map