synarcx 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Original work Copyright (c) 2024 OpenSpec-Powered Contributors
+Modified work Copyright (c) 2025 Adhi Rahmadian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,90 @@
+# SynArcX — Synapse Architecture Code Extension
+
+Spec-driven development workflow for AI coding agents.
+
+## Install
+
+```bash
+npm install -g synarcx
+```
+
+Or with pnpm:
+
+```bash
+pnpm add -g synarcx
+```
+
+Run `synarcx --help` to verify.
+
+## Quick Start
+
+```bash
+cd your-project
+synarcx init
+```
+
+Then in your AI tool:
+
+1. `/syn:sync` — generate project context (run once, re-run when the project shifts significantly)
+2. `/syn:explore "your idea"` — think through the problem, then follow the suggestion to `/syn:propose`
+3. `/syn:propose my-feature` — create proposal, specs, design, and tasks in one step
+4. `/syn:clarify` — sharpen the artifacts with targeted questions
+5. `/syn:analyze` — cross-artifact consistency check
+6. `/syn:apply` — implement the tasks
+7. `/syn:archive` — archive when done
+
+For bugs, use `/syn:debug` instead of `/syn:explore` — same flow, starting from a known error.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/syn:sync` | Generate or update the project constitution from README, AGENTS.md, package.json |
+| `/syn:explore` | Thinking partner — explore ideas, investigate problems, clarify requirements |
+| `/syn:debug` | Investigation tool — diagnose a known error and hand off findings to `/syn:propose` |
+| `/syn:propose` | Create a new change with proposal, specs, design, and tasks in one step |
+| `/syn:clarify` | Ask up to 5 targeted questions to sharpen artifacts before implementation |
+| `/syn:analyze` | Cross-artifact consistency check across proposal, specs, design, and tasks |
+| `/syn:apply` | Implement tasks from a change's task list |
+| `/syn:archive` | Archive a completed change and sync specs |
+
+## How It Works
+
+AI coding assistants are powerful but lose context fast when requirements live only in chat history. SynArcX adds a lightweight spec layer so you and your AI agree on what to build before any code is written.
+
+```
+syn:sync (once)
+
+explore ──┐
+           ├──► propose ──► clarify ──► analyze ──► apply ──► archive
+debug   ──┘
+```
+
+Each step suggests the next — you decide when to advance.
+
+Each change gets its own folder under `synspec/changes/` with:
+- `proposal.md` — what and why
+- `specs/` — what the system shall do
+- `design.md` — how to build it
+- `tasks.md` — implementation checklist
+
+## Supported Tools
+
+Works with 25+ AI coding assistants: Claude Code, OpenCode, Cursor, Gemini, GitHub Copilot, Cline, Windsurf, Codex, and more. Slash commands are generated per tool on `synarcx init`.
+
+## Development
+
+```bash
+git clone https://github.com/funara/synarcx
+cd synarcx
+pnpm install
+pnpm build
+pnpm link --global
+
+# rebuild after edits:
+pnpm build
+```
+
+## License
+
+MIT

package/bin/synarcx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -0,0 +1,474 @@
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import ora from 'ora';
+import path from 'path';
+import { promises as fs } from 'fs';
+import { AI_TOOLS } from '../core/config.js';
+import { UpdateCommand } from '../core/update.js';
+import { ListCommand } from '../core/list.js';
+import { ArchiveCommand } from '../core/archive.js';
+import { ViewCommand } from '../core/view.js';
+import { registerSpecCommand } from '../commands/spec.js';
+import { ChangeCommand } from '../commands/change.js';
+import { ValidateCommand } from '../commands/validate.js';
+import { ShowCommand } from '../commands/show.js';
+import { CompletionCommand } from '../commands/completion.js';
+import { FeedbackCommand } from '../commands/feedback.js';
+import { registerConfigCommand } from '../commands/config.js';
+import { registerSchemaCommand } from '../commands/schema.js';
+import { registerWorkspaceCommand } from '../commands/workspace.js';
+import { statusCommand, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+const program = new Command();
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+/**
+ * Get the full command path for nested commands.
+ * For example: 'change show' -> 'change:show'
+ */
+function getCommandPath(command) {
+    const names = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        // Skip the root 'synarcx' command
+        if (name && name !== 'synarcx') {
+            names.unshift(name);
+        }
+        current = current.parent;
+    }
+    return names.join(':') || 'synarcx';
+}
+program
+    .name('synarcx')
+    .description('Spec-driven development workflow for AI coding agents')
+    .version(version);
+// Global options
+program.option('--no-color', 'Disable color output');
+// Apply global flags before any command runs
+// Note: preAction receives (thisCommand, actionCommand) where:
+// - thisCommand: the command where hook was added (root program)
+// - actionCommand: the command actually being executed (subcommand)
+program.hook('preAction', async (thisCommand, _actionCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.color === false) {
+        process.env.NO_COLOR = '1';
+    }
+});
+const availableToolIds = AI_TOOLS.filter((tool) => tool.skillsDir).map((tool) => tool.value);
+const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
+program
+    .command('init [path]')
+    .description('Initialize SynArcX in your project')
+    .option('--tools <tools>', toolsOptionDescription)
+    .option('--force', 'Auto-cleanup legacy files without prompting')
+    .option('--profile <profile>', 'Override global config profile (core or custom)')
+    .action(async (targetPath = '.', options) => {
+    try {
+        // Validate that the path is a valid directory
+        const resolvedPath = path.resolve(targetPath);
+        try {
+            const stats = await fs.stat(resolvedPath);
+            if (!stats.isDirectory()) {
+                throw new Error(`Path "${targetPath}" is not a directory`);
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Directory doesn't exist, but we can create it
+                console.log(`Directory "${targetPath}" doesn't exist, it will be created.`);
+            }
+            else if (error.message && error.message.includes('not a directory')) {
+                throw error;
+            }
+            else {
+                throw new Error(`Cannot access path "${targetPath}": ${error.message}`);
+            }
+        }
+        const { InitCommand } = await import('../core/init.js');
+        const initCommand = new InitCommand({
+            tools: options?.tools,
+            force: options?.force,
+            profile: options?.profile,
+        });
+        await initCommand.execute(targetPath);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Hidden alias: 'experimental' -> 'init' for backwards compatibility
+program
+    .command('experimental', { hidden: true })
+    .description('Alias for init (deprecated)')
+    .option('--tool <tool-id>', 'Target AI tool (maps to --tools)')
+    .option('--no-interactive', 'Disable interactive prompts')
+    .action(async (options) => {
+    try {
+        console.log('Note: "synarcx experimental" is deprecated. Use "synarcx init" instead.');
+        const { InitCommand } = await import('../core/init.js');
+        const initCommand = new InitCommand({
+            tools: options?.tool,
+            interactive: options?.noInteractive === true ? false : undefined,
+        });
+        await initCommand.execute('.');
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('update [path]')
+    .description('Update SynArcX instruction files')
+    .option('--force', 'Force update even when tools are up to date')
+    .action(async (targetPath = '.', options) => {
+    try {
+        const resolvedPath = path.resolve(targetPath);
+        const updateCommand = new UpdateCommand({ force: options?.force });
+        await updateCommand.execute(resolvedPath);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('list')
+    .description('List items (changes by default). Use --specs to list specs.')
+    .option('--specs', 'List specs instead of changes')
+    .option('--changes', 'List changes explicitly (default)')
+    .option('--sort <order>', 'Sort order: "recent" (default) or "name"', 'recent')
+    .option('--json', 'Output as JSON (for programmatic use)')
+    .action(async (options) => {
+    try {
+        const listCommand = new ListCommand();
+        const mode = options?.specs ? 'specs' : 'changes';
+        const sort = options?.sort === 'name' ? 'name' : 'recent';
+        await listCommand.execute('.', mode, { sort, json: options?.json });
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('view')
+    .description('Display an interactive dashboard of specs and changes')
+    .action(async () => {
+    try {
+        const viewCommand = new ViewCommand();
+        await viewCommand.execute('.');
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Change command with subcommands
+const changeCmd = program
+    .command('change')
+    .description('Manage SynArcX change proposals');
+// Deprecation notice for noun-based commands
+changeCmd.hook('preAction', () => {
+    console.error('Warning: The "synarcx change ..." commands are deprecated. Prefer verb-first commands (e.g., "synarcx list", "synarcx validate --changes").');
+});
+changeCmd
+    .command('show [change-name]')
+    .description('Show a change proposal in JSON or markdown format')
+    .option('--json', 'Output as JSON')
+    .option('--deltas-only', 'Show only deltas (JSON only)')
+    .option('--requirements-only', 'Alias for --deltas-only (deprecated)')
+    .option('--no-interactive', 'Disable interactive prompts')
+    .action(async (changeName, options) => {
+    try {
+        const changeCommand = new ChangeCommand();
+        await changeCommand.show(changeName, options);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+    }
+});
+changeCmd
+    .command('list')
+    .description('List all active changes (DEPRECATED: use "synarcx list" instead)')
+    .option('--json', 'Output as JSON')
+    .option('--long', 'Show id and title with counts')
+    .action(async (options) => {
+    try {
+        console.error('Warning: "synarcx change list" is deprecated. Use "synarcx list".');
+        const changeCommand = new ChangeCommand();
+        await changeCommand.list(options);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+    }
+});
+changeCmd
+    .command('validate [change-name]')
+    .description('Validate a change proposal')
+    .option('--strict', 'Enable strict validation mode')
+    .option('--json', 'Output validation report as JSON')
+    .option('--no-interactive', 'Disable interactive prompts')
+    .action(async (changeName, options) => {
+    try {
+        const changeCommand = new ChangeCommand();
+        await changeCommand.validate(changeName, options);
+        if (typeof process.exitCode === 'number' && process.exitCode !== 0) {
+            process.exit(process.exitCode);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command('archive [change-name]')
+    .description('Archive a completed change and update main specs')
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .option('--skip-specs', 'Skip spec update operations (useful for infrastructure, tooling, or doc-only changes)')
+    .option('--no-validate', 'Skip validation (not recommended, requires confirmation)')
+    .action(async (changeName, options) => {
+    try {
+        const archiveCommand = new ArchiveCommand();
+        await archiveCommand.execute(changeName, options);
+    }
+    catch (error) {
+        console.log(); // Empty line for spacing
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+registerSpecCommand(program);
+registerConfigCommand(program);
+registerSchemaCommand(program);
+registerWorkspaceCommand(program);
+// Top-level validate command
+program
+    .command('validate [item-name]')
+    .description('Validate changes and specs')
+    .option('--all', 'Validate all changes and specs')
+    .option('--changes', 'Validate all changes')
+    .option('--specs', 'Validate all specs')
+    .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+    .option('--strict', 'Enable strict validation mode')
+    .option('--json', 'Output validation results as JSON')
+    .option('--concurrency <n>', 'Max concurrent validations (defaults to env SYNARCX_CONCURRENCY or 6)')
+    .option('--no-interactive', 'Disable interactive prompts')
+    .action(async (itemName, options) => {
+    try {
+        const validateCommand = new ValidateCommand();
+        await validateCommand.execute(itemName, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Top-level show command
+program
+    .command('show [item-name]')
+    .description('Show a change or spec')
+    .option('--json', 'Output as JSON')
+    .option('--type <type>', 'Specify item type when ambiguous: change|spec')
+    .option('--no-interactive', 'Disable interactive prompts')
+    // change-only flags
+    .option('--deltas-only', 'Show only deltas (JSON only, change)')
+    .option('--requirements-only', 'Alias for --deltas-only (deprecated, change)')
+    // spec-only flags
+    .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
+    .option('--no-scenarios', 'JSON only: Exclude scenario content')
+    .option('-r, --requirement <id>', 'JSON only: Show specific requirement by ID (1-based)')
+    // allow unknown options to pass-through to underlying command implementation
+    .allowUnknownOption(true)
+    .action(async (itemName, options) => {
+    try {
+        const showCommand = new ShowCommand();
+        await showCommand.execute(itemName, options ?? {});
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Feedback command
+program
+    .command('feedback <message>')
+    .description('Submit feedback')
+    .option('--body <text>', 'Detailed description for the feedback')
+    .action(async (message, options) => {
+    try {
+        const feedbackCommand = new FeedbackCommand();
+        await feedbackCommand.execute(message, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Completion command with subcommands
+const completionCmd = program
+    .command('completion')
+    .description('Manage shell completions for SynArcX CLI');
+completionCmd
+    .command('generate [shell]')
+    .description('Generate completion script for a shell (outputs to stdout)')
+    .action(async (shell) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.generate({ shell });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+completionCmd
+    .command('install [shell]')
+    .description('Install completion script for a shell')
+    .option('--verbose', 'Show detailed installation output')
+    .action(async (shell, options) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.install({ shell, verbose: options?.verbose });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+completionCmd
+    .command('uninstall [shell]')
+    .description('Uninstall completion script for a shell')
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .action(async (shell, options) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.uninstall({ shell, yes: options?.yes });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Hidden command for machine-readable completion data
+program
+    .command('__complete <type>', { hidden: true })
+    .description('Output completion data in machine-readable format (internal use)')
+    .action(async (type) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.complete({ type });
+    }
+    catch (error) {
+        // Silently fail for graceful shell completion experience
+        process.exitCode = 1;
+    }
+});
+// ═══════════════════════════════════════════════════════════
+// Workflow Commands (formerly experimental)
+// ═══════════════════════════════════════════════════════════
+// Status command
+program
+    .command('status')
+    .description('Display artifact completion status for a change')
+    .option('--change <id>', 'Change name to show status for')
+    .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        await statusCommand(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Instructions command
+program
+    .command('instructions [artifact]')
+    .description('Output enriched instructions for creating an artifact or applying tasks')
+    .option('--change <id>', 'Change name')
+    .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
+    .option('--json', 'Output as JSON')
+    .action(async (artifactId, options) => {
+    try {
+        // Special case: "apply" is not an artifact, but a command to get apply instructions
+        if (artifactId === 'apply') {
+            await applyInstructionsCommand(options);
+        }
+        else {
+            await instructionsCommand(artifactId, options);
+        }
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Templates command
+program
+    .command('templates')
+    .description('Show resolved template paths for all artifacts in a schema')
+    .option('--schema <name>', `Schema to use (default: ${DEFAULT_SCHEMA})`)
+    .option('--json', 'Output as JSON mapping artifact IDs to template paths')
+    .action(async (options) => {
+    try {
+        await templatesCommand(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Schemas command
+program
+    .command('schemas')
+    .description('List available workflow schemas with descriptions')
+    .option('--json', 'Output as JSON (for agent use)')
+    .action(async (options) => {
+    try {
+        await schemasCommand(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// New command group with change subcommand
+const newCmd = program.command('new').description('Create new items');
+newCmd
+    .command('change <name>')
+    .description('Create a new change directory')
+    .option('--description <text>', 'Description to add to README.md')
+    .option('--schema <name>', `Workflow schema to use (default: ${DEFAULT_SCHEMA})`)
+    .action(async (name, options) => {
+    try {
+        await newChangeCommand(name, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/commands/change.d.ts

@@ -0,0 +1,35 @@
+export declare class ChangeCommand {
+    private converter;
+    constructor();
+    /**
+     * Show a change proposal.
+     * - Text mode: raw markdown passthrough (no filters)
+     * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
+     *   Note: --requirements-only is deprecated alias for --deltas-only
+     */
+    show(changeName?: string, options?: {
+        json?: boolean;
+        requirementsOnly?: boolean;
+        deltasOnly?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    /**
+     * List active changes.
+     * - Text default: IDs only; --long prints minimal details (title, counts)
+     * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+     */
+    list(options?: {
+        json?: boolean;
+        long?: boolean;
+    }): Promise<void>;
+    validate(changeName?: string, options?: {
+        strict?: boolean;
+        json?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    private getActiveChanges;
+    private extractTitle;
+    private countTasks;
+    private printNextSteps;
+}
+//# sourceMappingURL=change.d.ts.map