@intoinside/praxis 1.0.1

package/src/commands/spec/archive.js

@@ -0,0 +1,114 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Action for 'praxis spec archive <spec-id>'
+ */
+export async function specArchiveAction(specId) {
+    const rootDir = process.cwd();
+    const specsDir = path.join(rootDir, '.praxis', 'specs');
+    const archiveDirBase = path.join(specsDir, 'archive');
+    // 1. Validate environment
+    if (!fs.existsSync(specsDir)) {
+        console.error('Error: Specs directory not found (.praxis/specs).');
+        return;
+    }
+    // 2. Find spec directory
+    const specDir = findSpecDirectory(specsDir, specId);
+    if (!specDir) {
+        console.error(`Error: Spec with ID '${specId}' not found.`);
+        return;
+    }
+    // Ensure we don't try to archive something already archived (though findSpecDirectory might exclude archive subfolder if implemented carefully)
+    if (specDir.includes(path.sep + 'archive' + path.sep)) {
+        console.error(`Error: Spec '${specId}' is already archived.`);
+        return;
+    }
+    // 3. Update status to Archived in spec.md
+    const specMdPath = path.join(specDir, 'spec.md');
+    if (fs.existsSync(specMdPath)) {
+        try {
+            let content = fs.readFileSync(specMdPath, 'utf-8');
+            // Simple regex to replace State: ... with State: Archived
+            // Supporting both "State: Draft" and "State:Draft"
+            const newState = 'State: Archived';
+            if (content.match(/^State:\s*.*$/m)) {
+                content = content.replace(/^State:\s*.*$/m, newState);
+            }
+            else {
+                // If no state found, maybe just append it or warn?
+                // Most specs should have a state. Let's prepend it if it looks like frontmatter.
+                content = newState + '\n' + content;
+            }
+            fs.writeFileSync(specMdPath, content, 'utf-8');
+            console.log(`Updated status to '${newState}' in ${specMdPath}`);
+        }
+        catch (error) {
+            console.error(`Warning: Could not update status in spec.md: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    // 4. Archive
+    try {
+        if (!fs.existsSync(archiveDirBase)) {
+            fs.mkdirSync(archiveDirBase, { recursive: true });
+        }
+        const targetDir = path.join(archiveDirBase, specId);
+        // Handle collision in archive
+        if (fs.existsSync(targetDir)) {
+            const timestamp = new Date().getTime();
+            const collisionDir = path.join(archiveDirBase, `${specId}_${timestamp}`);
+            console.warn(`Warning: Archive for '${specId}' already exists. Moving to ${collisionDir} instead.`);
+            fs.renameSync(specDir, collisionDir);
+            console.log(`Successfully archived spec '${specId}' to ${collisionDir}.`);
+        }
+        else {
+            console.log(`Archiving spec '${specId}' from ${specDir} to ${targetDir}...`);
+            fs.renameSync(specDir, targetDir);
+            console.log(`Successfully archived spec '${specId}'.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error archiving spec '${specId}': ${error.message}`);
+        }
+        else {
+            console.error(`Error archiving spec '${specId}': Unknown error`);
+        }
+    }
+}
+function findSpecDirectory(dir, targetId) {
+    try {
+        // Skip the archive directory itself during search
+        if (path.basename(dir) === 'archive') {
+            return null;
+        }
+        const list = fs.readdirSync(dir);
+        // Check if direct match exists
+        const directPath = path.join(dir, targetId);
+        if (fs.existsSync(directPath) && fs.statSync(directPath).isDirectory()) {
+            if (fs.existsSync(path.join(directPath, 'spec.md'))) {
+                return directPath;
+            }
+        }
+        // Recursive search
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                // If the directory name matches targetId
+                if (file === targetId) {
+                    if (fs.existsSync(path.join(filePath, 'spec.md'))) {
+                        return filePath;
+                    }
+                }
+                // Recurse
+                const found = findSpecDirectory(filePath, targetId);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    catch (e) {
+        // Ignore permission errors etc
+    }
+    return null;
+}

package/src/commands/spec/archive.ts

@@ -0,0 +1,121 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Action for 'praxis spec archive <spec-id>'
+ */
+export async function specArchiveAction(specId: string) {
+    const rootDir = process.cwd();
+    const specsDir = path.join(rootDir, '.praxis', 'specs');
+    const archiveDirBase = path.join(specsDir, 'archive');
+
+    // 1. Validate environment
+    if (!fs.existsSync(specsDir)) {
+        console.error('Error: Specs directory not found (.praxis/specs).');
+        return;
+    }
+
+    // 2. Find spec directory
+    const specDir = findSpecDirectory(specsDir, specId);
+    if (!specDir) {
+        console.error(`Error: Spec with ID '${specId}' not found.`);
+        return;
+    }
+
+    // Ensure we don't try to archive something already archived (though findSpecDirectory might exclude archive subfolder if implemented carefully)
+    if (specDir.includes(path.sep + 'archive' + path.sep)) {
+        console.error(`Error: Spec '${specId}' is already archived.`);
+        return;
+    }
+
+    // 3. Update status to Archived in spec.md
+    const specMdPath = path.join(specDir, 'spec.md');
+    if (fs.existsSync(specMdPath)) {
+        try {
+            let content = fs.readFileSync(specMdPath, 'utf-8');
+            // Simple regex to replace State: ... with State: Archived
+            // Supporting both "State: Draft" and "State:Draft"
+            const newState = 'State: Archived';
+            if (content.match(/^State:\s*.*$/m)) {
+                content = content.replace(/^State:\s*.*$/m, newState);
+            } else {
+                // If no state found, maybe just append it or warn?
+                // Most specs should have a state. Let's prepend it if it looks like frontmatter.
+                content = newState + '\n' + content;
+            }
+            fs.writeFileSync(specMdPath, content, 'utf-8');
+            console.log(`Updated status to '${newState}' in ${specMdPath}`);
+        } catch (error) {
+            console.error(`Warning: Could not update status in spec.md: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    // 4. Archive
+    try {
+        if (!fs.existsSync(archiveDirBase)) {
+            fs.mkdirSync(archiveDirBase, { recursive: true });
+        }
+
+        const targetDir = path.join(archiveDirBase, specId);
+
+        // Handle collision in archive
+        if (fs.existsSync(targetDir)) {
+            const timestamp = new Date().getTime();
+            const collisionDir = path.join(archiveDirBase, `${specId}_${timestamp}`);
+            console.warn(`Warning: Archive for '${specId}' already exists. Moving to ${collisionDir} instead.`);
+            fs.renameSync(specDir, collisionDir);
+            console.log(`Successfully archived spec '${specId}' to ${collisionDir}.`);
+        } else {
+            console.log(`Archiving spec '${specId}' from ${specDir} to ${targetDir}...`);
+            fs.renameSync(specDir, targetDir);
+            console.log(`Successfully archived spec '${specId}'.`);
+        }
+    } catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error archiving spec '${specId}': ${error.message}`);
+        } else {
+            console.error(`Error archiving spec '${specId}': Unknown error`);
+        }
+    }
+}
+
+function findSpecDirectory(dir: string, targetId: string): string | null {
+    try {
+        // Skip the archive directory itself during search
+        if (path.basename(dir) === 'archive') {
+            return null;
+        }
+
+        const list = fs.readdirSync(dir);
+
+        // Check if direct match exists
+        const directPath = path.join(dir, targetId);
+        if (fs.existsSync(directPath) && fs.statSync(directPath).isDirectory()) {
+            if (fs.existsSync(path.join(directPath, 'spec.md'))) {
+                return directPath;
+            }
+        }
+
+        // Recursive search
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+
+            if (stat.isDirectory()) {
+                // If the directory name matches targetId
+                if (file === targetId) {
+                    if (fs.existsSync(path.join(filePath, 'spec.md'))) {
+                        return filePath;
+                    }
+                }
+
+                // Recurse
+                const found = findSpecDirectory(filePath, targetId);
+                if (found) return found;
+            }
+        }
+    } catch (e) {
+        // Ignore permission errors etc
+    }
+    return null;
+}

package/src/commands/spec/delete.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Action for 'praxis spec delete <spec-id>'
+ */
+export declare function specDeleteAction(specId: string): Promise<void>;

package/src/commands/spec/delete.js

@@ -0,0 +1,70 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Action for 'praxis spec delete <spec-id>'
+ */
+export async function specDeleteAction(specId) {
+    const rootDir = process.cwd();
+    const specsDir = path.join(rootDir, '.praxis', 'specs');
+    // 1. Validate environment
+    if (!fs.existsSync(specsDir)) {
+        console.error('Error: Specs directory not found (.praxis/specs).');
+        return;
+    }
+    // 2. Find spec directory
+    const specDir = findSpecDirectory(specsDir, specId);
+    if (!specDir) {
+        console.error(`Error: Spec with ID '${specId}' not found.`);
+        return;
+    }
+    // 3. Delete
+    try {
+        console.log(`Deleting spec '${specId}' at ${specDir}...`);
+        fs.rmSync(specDir, { recursive: true, force: true });
+        console.log(`Successfully deleted spec '${specId}' and its artifacts.`);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error deleting spec '${specId}': ${error.message}`);
+        }
+        else {
+            console.error(`Error deleting spec '${specId}': Unknown error`);
+        }
+    }
+}
+function findSpecDirectory(dir, targetId) {
+    try {
+        const list = fs.readdirSync(dir);
+        // Check if direct match exists
+        const directPath = path.join(dir, targetId);
+        if (fs.existsSync(directPath) && fs.statSync(directPath).isDirectory()) {
+            // Optional: Check if it looks like a spec (has spec.md)?
+            // For now, we trust the ID matches the directory name.
+            // But to be safer/consistent with derive.ts:
+            if (fs.existsSync(path.join(directPath, 'spec.md'))) {
+                return directPath;
+            }
+        }
+        // Recursive search
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                // If the directory name matches targetId
+                if (file === targetId) {
+                    if (fs.existsSync(path.join(filePath, 'spec.md'))) {
+                        return filePath;
+                    }
+                }
+                // Recurse
+                const found = findSpecDirectory(filePath, targetId);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    catch (e) {
+        // Ignore permission errors etc
+    }
+    return null;
+}

package/src/commands/spec/delete.ts

@@ -0,0 +1,75 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Action for 'praxis spec delete <spec-id>'
+ */
+export async function specDeleteAction(specId: string) {
+    const rootDir = process.cwd();
+    const specsDir = path.join(rootDir, '.praxis', 'specs');
+
+    // 1. Validate environment
+    if (!fs.existsSync(specsDir)) {
+        console.error('Error: Specs directory not found (.praxis/specs).');
+        return;
+    }
+
+    // 2. Find spec directory
+    const specDir = findSpecDirectory(specsDir, specId);
+    if (!specDir) {
+        console.error(`Error: Spec with ID '${specId}' not found.`);
+        return;
+    }
+
+    // 3. Delete
+    try {
+        console.log(`Deleting spec '${specId}' at ${specDir}...`);
+        fs.rmSync(specDir, { recursive: true, force: true });
+        console.log(`Successfully deleted spec '${specId}' and its artifacts.`);
+    } catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error deleting spec '${specId}': ${error.message}`);
+        } else {
+            console.error(`Error deleting spec '${specId}': Unknown error`);
+        }
+    }
+}
+
+function findSpecDirectory(dir: string, targetId: string): string | null {
+    try {
+        const list = fs.readdirSync(dir);
+
+        // Check if direct match exists
+        const directPath = path.join(dir, targetId);
+        if (fs.existsSync(directPath) && fs.statSync(directPath).isDirectory()) {
+            // Optional: Check if it looks like a spec (has spec.md)?
+            // For now, we trust the ID matches the directory name.
+            // But to be safer/consistent with derive.ts:
+            if (fs.existsSync(path.join(directPath, 'spec.md'))) {
+                return directPath;
+            }
+        }
+
+        // Recursive search
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+
+            if (stat.isDirectory()) {
+                // If the directory name matches targetId
+                if (file === targetId) {
+                    if (fs.existsSync(path.join(filePath, 'spec.md'))) {
+                        return filePath;
+                    }
+                }
+
+                // Recurse
+                const found = findSpecDirectory(filePath, targetId);
+                if (found) return found;
+            }
+        }
+    } catch (e) {
+        // Ignore permission errors etc
+    }
+    return null;
+}

package/src/commands/spec/derive.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Action for 'praxis spec derive --from <intent-id>'
+ */
+export declare function specDeriveAction(options: {
+    from: string;
+}): Promise<void>;

package/src/commands/spec/derive.js

@@ -0,0 +1,107 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Action for 'praxis spec derive --from <intent-id>'
+ */
+export async function specDeriveAction(options) {
+    const intentId = options.from;
+    const rootDir = process.cwd();
+    const intentsDir = path.join(rootDir, '.praxis', 'intents');
+    const templatePath = path.join(rootDir, '.praxis', 'templates', 'spec-template.md');
+    // 1. Validate environment
+    if (!fs.existsSync(intentsDir)) {
+        console.error('Error: Intents directory not found (.praxis/intents).');
+        return;
+    }
+    if (!fs.existsSync(templatePath)) {
+        console.error(`Error: Spec template not found at ${templatePath}`);
+        return;
+    }
+    // 2. Find intent file
+    const intentFile = findIntentFile(intentsDir, intentId);
+    if (!intentFile) {
+        console.error(`Error: Intent with ID '${intentId}' not found.`);
+        return;
+    }
+    // 3. Read content
+    const intentContent = fs.readFileSync(intentFile, 'utf8');
+    const templateContent = fs.readFileSync(templatePath, 'utf8');
+    // 4. Generate Prompt
+    const prompt = generateAiPrompt(intentId, intentContent, templateContent);
+    // 5. Output
+    console.log('\n--- IDE AI CHAT PROMPT ---');
+    console.log('Copy and paste the following into your IDE chat to generate the specification:');
+    console.log('--------------------------');
+    console.log(prompt);
+    console.log('--------------------------\n');
+}
+function findIntentFile(dir, targetId) {
+    try {
+        const list = fs.readdirSync(dir);
+        // Check if direct match exists (optimization)
+        const directPath = path.join(dir, targetId, 'intent.md');
+        if (fs.existsSync(directPath)) {
+            return directPath;
+        }
+        // Recursive search
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                // If the directory name *is* the ID, check for intent.md inside
+                if (file === targetId) {
+                    const potentialIntent = path.join(filePath, 'intent.md');
+                    if (fs.existsSync(potentialIntent)) {
+                        return potentialIntent;
+                    }
+                }
+                // Otherwise recurse
+                const found = findIntentFile(filePath, targetId);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    catch (e) {
+        // Ignore permission errors etc during search
+    }
+    return null;
+}
+function generateAiPrompt(intentId, intentContent, templateContent) {
+    return `You are an expert software architect and product owner.
+I need to generate a specific technical specification (Spec) for an Intent in my project.
+
+**Source Intent ID**: ${intentId}
+
+**Context**:
+An Intent can result in multiple Specifications (Specs). Each Spec represents a concrete feature or component derived from the Intent.
+To keep things organized, every Spec needs a unique identifier.
+
+**Task**:
+1.  **Analyze** the Intent provided below. Understand the goal and identify the specific scope for *this* specification.
+2.  **Generate a Spec ID**:
+    -   Create a concise, kebab-case string (max 20 chars) that represents the content of this specific spec.
+    -   Example: If the intent is "create-user-profile", this spec might be "profile-api" or "profile-ui".
+3.  **Generate the Specification** using the provided Template.
+    -   Fill in ALL sections of the template.
+    -   Use the intent information to populate "User Scenarios", "Requirements", etc.
+    -   Ensure the Spec is detailed enough for an AI agent to implement the code later.
+    -   Do NOT change the structure of the template.
+    -   Set Status to "Draft".
+4.  **Output** the full Markdown content of the new specification file.
+    -   **Important**: The file path MUST be: \`.praxis/specs/<intent-id><your-generated-spec-id>/spec.md\`
+
+---
+**INTENT CONTENT**:
+\`\`\`markdown
+${intentContent}
+\`\`\`
+
+---
+**SPEC TEMPLATE**:
+\`\`\`markdown
+${templateContent}
+\`\`\`
+
+Please generate the file creation tool call (if available) or the full markdown content with the specified path now.`;
+}

package/src/commands/spec/derive.ts

@@ -0,0 +1,117 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Action for 'praxis spec derive --from <intent-id>'
+ */
+export async function specDeriveAction(options: { from: string }) {
+    const intentId = options.from;
+    const rootDir = process.cwd();
+    const intentsDir = path.join(rootDir, '.praxis', 'intents');
+    const templatePath = path.join(rootDir, '.praxis', 'templates', 'spec-template.md');
+
+    // 1. Validate environment
+    if (!fs.existsSync(intentsDir)) {
+        console.error('Error: Intents directory not found (.praxis/intents).');
+        return;
+    }
+    if (!fs.existsSync(templatePath)) {
+        console.error(`Error: Spec template not found at ${templatePath}`);
+        return;
+    }
+
+    // 2. Find intent file
+    const intentFile = findIntentFile(intentsDir, intentId);
+    if (!intentFile) {
+        console.error(`Error: Intent with ID '${intentId}' not found.`);
+        return;
+    }
+
+    // 3. Read content
+    const intentContent = fs.readFileSync(intentFile, 'utf8');
+    const templateContent = fs.readFileSync(templatePath, 'utf8');
+
+    // 4. Generate Prompt
+    const prompt = generateAiPrompt(intentId, intentContent, templateContent);
+
+    // 5. Output
+    console.log('\n--- IDE AI CHAT PROMPT ---');
+    console.log('Copy and paste the following into your IDE chat to generate the specification:');
+    console.log('--------------------------');
+    console.log(prompt);
+    console.log('--------------------------\n');
+}
+
+function findIntentFile(dir: string, targetId: string): string | null {
+    try {
+        const list = fs.readdirSync(dir);
+
+        // Check if direct match exists (optimization)
+        const directPath = path.join(dir, targetId, 'intent.md');
+        if (fs.existsSync(directPath)) {
+            return directPath;
+        }
+
+        // Recursive search
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+
+            if (stat.isDirectory()) {
+                // If the directory name *is* the ID, check for intent.md inside
+                if (file === targetId) {
+                    const potentialIntent = path.join(filePath, 'intent.md');
+                    if (fs.existsSync(potentialIntent)) {
+                        return potentialIntent;
+                    }
+                }
+
+                // Otherwise recurse
+                const found = findIntentFile(filePath, targetId);
+                if (found) return found;
+            }
+        }
+    } catch (e) {
+        // Ignore permission errors etc during search
+    }
+    return null;
+}
+
+function generateAiPrompt(intentId: string, intentContent: string, templateContent: string): string {
+    return `You are an expert software architect and product owner.
+I need to generate a specific technical specification (Spec) for an Intent in my project.
+
+**Source Intent ID**: ${intentId}
+
+**Context**:
+An Intent can result in multiple Specifications (Specs). Each Spec represents a concrete feature or component derived from the Intent.
+To keep things organized, every Spec needs a unique identifier.
+
+**Task**:
+1.  **Analyze** the Intent provided below. Understand the goal and identify the specific scope for *this* specification.
+2.  **Generate a Spec ID**:
+    -   Create a concise, kebab-case string (max 20 chars) that represents the content of this specific spec.
+    -   Example: If the intent is "create-user-profile", this spec might be "profile-api" or "profile-ui".
+3.  **Generate the Specification** using the provided Template.
+    -   Fill in ALL sections of the template.
+    -   Use the intent information to populate "User Scenarios", "Requirements", etc.
+    -   Ensure the Spec is detailed enough for an AI agent to implement the code later.
+    -   Do NOT change the structure of the template.
+    -   Set Status to "Draft".
+4.  **Output** the full Markdown content of the new specification file.
+    -   **Important**: The file path MUST be: \`.praxis/specs/<intent-id><your-generated-spec-id>/spec.md\`
+
+---
+**INTENT CONTENT**:
+\`\`\`markdown
+${intentContent}
+\`\`\`
+
+---
+**SPEC TEMPLATE**:
+\`\`\`markdown
+${templateContent}
+\`\`\`
+
+Please generate the file creation tool call (if available) or the full markdown content with the specified path now.`;
+}

package/src/core/command-generation/adapters/antigravity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Antigravity Command Adapter
+ *
+ * Formats commands for Antigravity following its frontmatter specification.
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * Antigravity adapter for command generation.
+ * File path: .agent/workflows/praxis-<id>.md
+ * Frontmatter: description
+ */
+export declare const antigravityAdapter: ToolCommandAdapter;

package/src/core/command-generation/adapters/antigravity.js

@@ -0,0 +1,25 @@
+/**
+ * Antigravity Command Adapter
+ *
+ * Formats commands for Antigravity following its frontmatter specification.
+ */
+import path from 'path';
+/**
+ * Antigravity adapter for command generation.
+ * File path: .agent/workflows/praxis-<id>.md
+ * Frontmatter: description
+ */
+export const antigravityAdapter = {
+    toolId: 'antigravity',
+    getFilePath(commandId) {
+        return path.join('.agent', 'workflows', `praxis-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+description: ${content.description}
+---
+
+${content.body}
+`;
+    },
+};

package/src/core/command-generation/adapters/antigravity.ts

@@ -0,0 +1,30 @@
+/**
+ * Antigravity Command Adapter
+ *
+ * Formats commands for Antigravity following its frontmatter specification.
+ */
+
+import path from 'path';
+import type { CommandContent, ToolCommandAdapter } from '../types.js';
+
+/**
+ * Antigravity adapter for command generation.
+ * File path: .agent/workflows/praxis-<id>.md
+ * Frontmatter: description
+ */
+export const antigravityAdapter: ToolCommandAdapter = {
+    toolId: 'antigravity',
+
+    getFilePath(commandId: string): string {
+        return path.join('.agent', 'workflows', `praxis-${commandId}.md`);
+    },
+
+    formatFile(content: CommandContent): string {
+        return `---
+description: ${content.description}
+---
+
+${content.body}
+`;
+    },
+};