@uxmaltech/collab-cli 0.1.0

package/dist/stages/repo-scaffold.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repoScaffoldStage = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const PLACEHOLDER_MARKER = '<!-- AI-GENERATED: PLACEHOLDER -->';
+function buildRepoScaffoldEntries() {
+    return [
+        {
+            relativePath: 'knowledge/axioms/README.md',
+            content: [
+                '# Axioms',
+                '',
+                PLACEHOLDER_MARKER,
+                '',
+                'Project-specific foundational truths. Generated by AI analysis or written manually.',
+                '',
+                '## Adding Axioms',
+                '',
+                'Each axiom should have:',
+                '- A unique ID (e.g., `AX-001`)',
+                '- A confidence level (`experimental | provisional | verified`)',
+                '- A clear statement and rationale',
+                '',
+            ].join('\n'),
+        },
+        {
+            relativePath: 'knowledge/decisions/README.md',
+            content: [
+                '# Architecture Decision Records',
+                '',
+                PLACEHOLDER_MARKER,
+                '',
+                'Project-specific ADRs. Follow the format:',
+                '',
+                '- **Context**: What prompted the decision',
+                '- **Decision**: What was decided',
+                '- **Consequences**: Trade-offs and outcomes',
+                '',
+            ].join('\n'),
+        },
+        {
+            relativePath: 'knowledge/conventions/README.md',
+            content: [
+                '# Conventions',
+                '',
+                PLACEHOLDER_MARKER,
+                '',
+                'Project-specific naming, versioning, and code conventions.',
+                '',
+            ].join('\n'),
+        },
+        {
+            relativePath: 'knowledge/anti-patterns/README.md',
+            content: [
+                '# Anti-Patterns',
+                '',
+                PLACEHOLDER_MARKER,
+                '',
+                'Documented violations and patterns to avoid in this project.',
+                '',
+            ].join('\n'),
+        },
+        {
+            relativePath: 'domains/README.md',
+            content: [
+                '# Domains',
+                '',
+                PLACEHOLDER_MARKER,
+                '',
+                'Project-specific domain boundaries, responsibilities, and public APIs.',
+                '',
+            ].join('\n'),
+        },
+    ];
+}
+function generateRepoScaffold(ctx) {
+    const repoDir = ctx.config.repoDir;
+    const entries = buildRepoScaffoldEntries();
+    let created = 0;
+    let skipped = 0;
+    for (const entry of entries) {
+        const target = node_path_1.default.join(repoDir, entry.relativePath);
+        if (!ctx.executor.dryRun && node_fs_1.default.existsSync(target)) {
+            ctx.logger.debug(`Repo scaffold file already exists, skipping: ${entry.relativePath}`);
+            skipped++;
+            continue;
+        }
+        ctx.executor.ensureDirectory(node_path_1.default.dirname(target));
+        ctx.executor.writeFile(target, entry.content, {
+            description: `scaffold repo/${entry.relativePath}`,
+        });
+        created++;
+    }
+    ctx.logger.info(`Repo scaffold: ${created} file(s) created, ${skipped} existing file(s) preserved.`);
+}
+exports.repoScaffoldStage = {
+    id: 'repo-scaffold',
+    title: 'Generate project architecture scaffold',
+    recovery: [
+        'Verify write permissions for docs/architecture/repo/ directory.',
+        'Run collab init --resume to retry scaffold generation.',
+    ],
+    run: (ctx) => {
+        generateRepoScaffold(ctx);
+    },
+};

package/dist/templates/canon/contracts-readme.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractsReadme = void 0;
+exports.contractsReadme = `# Contracts
+
+> API contracts, interfaces, and integration boundaries.
+
+This directory documents the contracts between domains, services, and
+external systems.
+
+## Types of Contracts
+
+- **Internal** — Interfaces between domains within the codebase.
+- **External** — APIs exposed to or consumed from external systems.
+- **Event** — Async message contracts (if applicable).
+
+## Format
+
+\`\`\`markdown
+# Contract: <Name>
+
+**Type:** internal | external | event
+**Confidence:** HIGH | MEDIUM | LOW
+
+## Parties
+
+Who produces and who consumes this contract.
+
+## Specification
+
+The contract details (endpoints, message formats, interfaces).
+
+## Guarantees
+
+What invariants this contract maintains.
+\`\`\`
+
+<!-- AI-GENERATED: PLACEHOLDER -->
+`;

package/dist/templates/canon/domain-readme.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.domainReadme = void 0;
+exports.domainReadme = `# Domains
+
+> Bounded contexts and domain boundaries identified in this codebase.
+
+Each domain is documented in its own file describing:
+
+- **Responsibilities** — What the domain owns.
+- **Boundaries** — Where the domain starts and ends.
+- **Dependencies** — Which other domains it depends on.
+- **Public API** — How other domains interact with it.
+
+## Format
+
+\`\`\`markdown
+# Domain: <Name>
+
+**Confidence:** HIGH | MEDIUM | LOW
+
+## Responsibilities
+
+What this domain is responsible for.
+
+## Boundaries
+
+Key directories, modules, or packages that belong to this domain.
+
+## Dependencies
+
+Other domains this domain depends on and why.
+
+## Public API
+
+Contracts or interfaces this domain exposes.
+\`\`\`
+
+<!-- AI-GENERATED: PLACEHOLDER -->
+`;

package/dist/templates/canon/evolution/changelog.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deprecatedTemplate = exports.upgradeGuideTemplate = exports.changelogTemplate = void 0;
+exports.changelogTemplate = `# Architecture Changelog
+
+> Track of significant architectural changes over time.
+
+## Format
+
+Entries are ordered newest-first, grouped by date.
+
+---
+
+## [Unreleased]
+
+- Initial canonical architecture scaffold generated by \`collab init\`.
+`;
+exports.upgradeGuideTemplate = `# Upgrade Guide
+
+> Instructions for migrating between canonical schema versions.
+
+## Current Version: 1.0.0
+
+This is the initial version. No migrations needed.
+
+---
+
+## Future Migrations
+
+When the schema version changes, migration instructions will be
+documented here with before/after examples.
+`;
+exports.deprecatedTemplate = `# Deprecated Entries
+
+> Canonical entries that have been superseded or invalidated.
+
+When an axiom, decision, convention, or anti-pattern is no longer valid,
+it is moved here with a rationale explaining why.
+
+## Format
+
+\`\`\`markdown
+### <ID>: <Title>
+
+**Deprecated:** YYYY-MM-DD
+**Reason:** Why this entry was deprecated.
+**Superseded by:** <new-ID> (if applicable)
+\`\`\`
+
+---
+
+_No deprecated entries yet._
+`;

package/dist/templates/canon/governance/confidence-levels.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confidenceLevelsTemplate = void 0;
+exports.confidenceLevelsTemplate = `# Confidence Levels
+
+> How confidence is assigned to canonical entries.
+
+## Levels
+
+### HIGH
+
+The entry is verified by multiple independent signals:
+
+- Source code structure confirms the pattern.
+- Tests exercise the behavior.
+- Existing documentation corroborates the decision.
+
+### MEDIUM
+
+The entry is verified by at least one signal:
+
+- Code structure suggests the pattern.
+- A single test or doc reference supports it.
+
+### LOW
+
+The entry is inferred from indirect evidence:
+
+- Code comments or naming conventions hint at the pattern.
+- AI analysis identified it but no direct verification exists.
+
+## Promotion Rules
+
+- Entries at **LOW** should be verified within 2 sprint cycles.
+- If not verified, they move to \`evolution/deprecated.md\` with rationale.
+- Entries at **MEDIUM** can be promoted to **HIGH** when additional
+  verification signals are added (tests, docs, or PR review confirmation).
+`;

package/dist/templates/canon/governance/implementation-process.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.implementationProcessTemplate = void 0;
+exports.implementationProcessTemplate = `# Implementation Process
+
+> GOV-R-001 — How canonical architecture documentation is maintained.
+
+## Process Overview
+
+1. **Analysis** — AI or developer analyzes the repository to identify
+   architectural patterns, decisions, and conventions.
+2. **Generation** — Canonical files are generated or updated in
+   \`docs/architecture/\`.
+3. **Review** — Changes go through the standard PR review process.
+4. **Merge** — Accepted changes are merged to the main branch.
+5. **Ingestion** (indexed mode only) — Merged files are ingested into the
+   vector and graph databases for retrieval.
+
+## PR Workflow
+
+Every pull request that modifies source code SHOULD also update the
+relevant canonical files:
+
+- New architectural decisions → \`knowledge/decisions/ADR-NNN-*.md\`
+- New conventions observed → \`knowledge/conventions/CN-NNN-*.md\`
+- Anti-pattern fixes → \`knowledge/anti-patterns/AP-NNN-*.md\`
+- Domain boundary changes → \`domains/*.md\`
+
+## Automation
+
+- \`collab init\` generates the initial scaffold and runs AI analysis.
+- CI workflows validate architecture consistency on PRs.
+- Merge workflows trigger re-ingestion (indexed mode only).
+`;

package/dist/templates/canon/governance/review-process.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviewProcessTemplate = void 0;
+exports.reviewProcessTemplate = `# Review Process
+
+> How changes to the canonical architecture are reviewed and approved.
+
+## Review Criteria
+
+All changes to \`docs/architecture/\` MUST be reviewed for:
+
+1. **Accuracy** — Does the entry reflect the actual codebase?
+2. **Completeness** — Are all relevant aspects covered?
+3. **Consistency** — Does it follow the established formats (ID schemes,
+   confidence levels)?
+4. **Non-duplication** — Is it truly new knowledge, not a restatement?
+
+## Reviewers
+
+- Architecture changes SHOULD be reviewed by at least one developer
+  familiar with the affected domain.
+- AI-generated entries MUST be reviewed by a human before merge.
+
+## Merge Policy
+
+- All canonical changes go through standard PR review.
+- Auto-generated entries include an \`<!-- AI-GENERATED -->\` marker.
+- Reviewers should focus on verifying accuracy, not style.
+`;

package/dist/templates/canon/governance/schema-versioning.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaVersioningTemplate = void 0;
+exports.schemaVersioningTemplate = `# Schema Versioning
+
+> Policy for versioning the canonical architecture schema.
+
+## Version Format
+
+The canonical schema follows semantic versioning: \`MAJOR.MINOR.PATCH\`
+
+- **MAJOR** — Breaking changes to the directory structure or file formats.
+- **MINOR** — New categories, fields, or optional sections added.
+- **PATCH** — Clarifications, typo fixes, template updates.
+
+## Current Version
+
+\`1.0.0\`
+
+## Compatibility
+
+- Tools MUST check the schema version before processing canonical files.
+- Older tools SHOULD gracefully handle unknown fields (ignore, don't fail).
+- Migration guides live in \`evolution/upgrade-guide.md\`.
+`;

package/dist/templates/canon/governance/what-enters-the-canon.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whatEntersTheCanonTemplate = void 0;
+exports.whatEntersTheCanonTemplate = `# What Enters the Canon
+
+> This document defines the governance rules for the canonical architecture
+> documentation of this repository.
+
+## Purpose
+
+The **canon** is the single source of truth for architecture knowledge.
+Every statement that lives here MUST be verifiable against the actual codebase.
+
+## Entry Criteria
+
+A piece of knowledge enters the canon when it meets ALL of the following:
+
+1. **Verifiable** — It can be confirmed by inspecting the source code.
+2. **Stable** — It reflects a deliberate decision, not an accident or WIP.
+3. **Impactful** — It affects how developers reason about or extend the system.
+
+## Categories
+
+| Category | ID Format | Description |
+|----------|-----------|-------------|
+| Axioms | AX-NNN | Invariants that MUST always hold |
+| Decisions | ADR-NNN | Architecture Decision Records |
+| Conventions | CN-NNN | Coding and design conventions |
+| Anti-patterns | AP-NNN | Known pitfalls to avoid |
+
+## Confidence Levels
+
+Each entry carries a confidence level:
+
+- **HIGH** — Verified by multiple signals (code, tests, docs).
+- **MEDIUM** — Verified by at least one signal.
+- **LOW** — Inferred, pending verification.
+
+## Lifecycle
+
+1. **Proposed** — Entry drafted (manually or by AI analysis).
+2. **Accepted** — Reviewed and merged via PR.
+3. **Deprecated** — Superseded; moved to \`evolution/deprecated.md\`.
+`;

package/dist/templates/canon/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemPromptTemplate = exports.deprecatedTemplate = exports.upgradeGuideTemplate = exports.changelogTemplate = exports.contractsReadme = exports.domainReadme = exports.knowledgeAntiPatternsReadme = exports.knowledgeConventionsReadme = exports.knowledgeDecisionsReadme = exports.knowledgeAxiomsReadme = exports.reviewProcessTemplate = exports.confidenceLevelsTemplate = exports.schemaVersioningTemplate = exports.implementationProcessTemplate = exports.whatEntersTheCanonTemplate = void 0;
+var what_enters_the_canon_1 = require("./governance/what-enters-the-canon");
+Object.defineProperty(exports, "whatEntersTheCanonTemplate", { enumerable: true, get: function () { return what_enters_the_canon_1.whatEntersTheCanonTemplate; } });
+var implementation_process_1 = require("./governance/implementation-process");
+Object.defineProperty(exports, "implementationProcessTemplate", { enumerable: true, get: function () { return implementation_process_1.implementationProcessTemplate; } });
+var schema_versioning_1 = require("./governance/schema-versioning");
+Object.defineProperty(exports, "schemaVersioningTemplate", { enumerable: true, get: function () { return schema_versioning_1.schemaVersioningTemplate; } });
+var confidence_levels_1 = require("./governance/confidence-levels");
+Object.defineProperty(exports, "confidenceLevelsTemplate", { enumerable: true, get: function () { return confidence_levels_1.confidenceLevelsTemplate; } });
+var review_process_1 = require("./governance/review-process");
+Object.defineProperty(exports, "reviewProcessTemplate", { enumerable: true, get: function () { return review_process_1.reviewProcessTemplate; } });
+var knowledge_readme_1 = require("./knowledge-readme");
+Object.defineProperty(exports, "knowledgeAxiomsReadme", { enumerable: true, get: function () { return knowledge_readme_1.knowledgeAxiomsReadme; } });
+Object.defineProperty(exports, "knowledgeDecisionsReadme", { enumerable: true, get: function () { return knowledge_readme_1.knowledgeDecisionsReadme; } });
+Object.defineProperty(exports, "knowledgeConventionsReadme", { enumerable: true, get: function () { return knowledge_readme_1.knowledgeConventionsReadme; } });
+Object.defineProperty(exports, "knowledgeAntiPatternsReadme", { enumerable: true, get: function () { return knowledge_readme_1.knowledgeAntiPatternsReadme; } });
+var domain_readme_1 = require("./domain-readme");
+Object.defineProperty(exports, "domainReadme", { enumerable: true, get: function () { return domain_readme_1.domainReadme; } });
+var contracts_readme_1 = require("./contracts-readme");
+Object.defineProperty(exports, "contractsReadme", { enumerable: true, get: function () { return contracts_readme_1.contractsReadme; } });
+var changelog_1 = require("./evolution/changelog");
+Object.defineProperty(exports, "changelogTemplate", { enumerable: true, get: function () { return changelog_1.changelogTemplate; } });
+Object.defineProperty(exports, "upgradeGuideTemplate", { enumerable: true, get: function () { return changelog_1.upgradeGuideTemplate; } });
+Object.defineProperty(exports, "deprecatedTemplate", { enumerable: true, get: function () { return changelog_1.deprecatedTemplate; } });
+var system_prompt_1 = require("./system-prompt");
+Object.defineProperty(exports, "systemPromptTemplate", { enumerable: true, get: function () { return system_prompt_1.systemPromptTemplate; } });

package/dist/templates/canon/knowledge-readme.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.knowledgeAntiPatternsReadme = exports.knowledgeConventionsReadme = exports.knowledgeDecisionsReadme = exports.knowledgeAxiomsReadme = void 0;
+exports.knowledgeAxiomsReadme = `# Axioms
+
+> Invariants that MUST always hold in this codebase.
+
+Axioms use the ID format \`AX-NNN\` and represent fundamental truths about
+the system that should never be violated.
+
+## Format
+
+Each axiom file follows this structure:
+
+\`\`\`markdown
+# AX-NNN: Short Title
+
+**Confidence:** HIGH | MEDIUM | LOW
+**Verified:** YYYY-MM-DD
+
+## Statement
+
+One-sentence invariant.
+
+## Rationale
+
+Why this axiom exists.
+
+## Verification
+
+How to confirm this axiom holds.
+\`\`\`
+
+<!-- AI-GENERATED: PLACEHOLDER -->
+`;
+exports.knowledgeDecisionsReadme = `# Architectural Decisions
+
+> ADRs documenting key architectural choices.
+
+Decisions use the ID format \`ADR-NNN\` and follow a lightweight ADR format.
+
+## Format
+
+Each decision file follows this structure:
+
+\`\`\`markdown
+# ADR-NNN: Short Title
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** YYYY-MM-DD
+**Confidence:** HIGH | MEDIUM | LOW
+
+## Context
+
+What prompted this decision.
+
+## Decision
+
+What was decided.
+
+## Consequences
+
+What follows from this decision.
+\`\`\`
+
+<!-- AI-GENERATED: PLACEHOLDER -->
+`;
+exports.knowledgeConventionsReadme = `# Conventions
+
+> Coding and design conventions followed in this codebase.
+
+Conventions use the ID format \`CN-NNN\`.
+
+## Format
+
+Each convention file follows this structure:
+
+\`\`\`markdown
+# CN-NNN: Short Title
+
+**Confidence:** HIGH | MEDIUM | LOW
+**Scope:** project | module | file
+
+## Convention
+
+What the convention is.
+
+## Examples
+
+Code examples demonstrating the convention.
+
+## Rationale
+
+Why this convention exists.
+\`\`\`
+
+<!-- AI-GENERATED: PLACEHOLDER -->
+`;
+exports.knowledgeAntiPatternsReadme = `# Anti-Patterns
+
+> Known pitfalls and patterns to avoid in this codebase.
+
+Anti-patterns use the ID format \`AP-NNN\`.
+
+## Format
+
+Each anti-pattern file follows this structure:
+
+\`\`\`markdown
+# AP-NNN: Short Title
+
+**Confidence:** HIGH | MEDIUM | LOW
+**Severity:** critical | warning | info
+
+## Problem
+
+What the anti-pattern looks like.
+
+## Why It's Harmful
+
+Why this pattern should be avoided.
+
+## Alternative
+
+The preferred approach.
+\`\`\`
+
+<!-- AI-GENERATED: PLACEHOLDER -->
+`;

package/dist/templates/canon/system-prompt.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemPromptTemplate = void 0;
+exports.systemPromptTemplate = `You are an architecture analyst. Your task is to analyze a software repository
+and generate canonical architecture documentation following the collab-architecture format.
+
+## Output Requirements
+
+For each category, generate entries using the specified ID format:
+
+### Axioms (AX-NNN)
+Identify invariants that MUST always hold in this codebase.
+- Look for patterns enforced by types, assertions, or structural constraints.
+- Each axiom should be a single verifiable statement.
+
+### Architectural Decisions (ADR-NNN)
+Document key architectural choices visible in the code.
+- Framework and library selections.
+- Structural patterns (monolith, microservices, modular monolith).
+- Data flow and state management approaches.
+
+### Conventions (CN-NNN)
+Identify coding and design conventions consistently followed.
+- Naming patterns, file organization, error handling strategies.
+- Testing patterns, import conventions, module boundaries.
+
+### Anti-Patterns (AP-NNN)
+Flag patterns that should be avoided based on the codebase context.
+- Inconsistencies that suggest accidental complexity.
+- Deprecated patterns still present that should be migrated.
+
+### Domains
+Identify bounded contexts and domain boundaries.
+- Group related functionality into logical domains.
+- Map dependencies between domains.
+
+## Output Format
+
+Return a JSON object with the following structure:
+
+\`\`\`json
+{
+  "axioms": [
+    {
+      "id": "AX-001",
+      "title": "Short title",
+      "confidence": "HIGH|MEDIUM|LOW",
+      "statement": "The invariant statement",
+      "rationale": "Why this axiom exists",
+      "verification": "How to verify this holds"
+    }
+  ],
+  "decisions": [
+    {
+      "id": "ADR-001",
+      "title": "Short title",
+      "status": "Accepted",
+      "confidence": "HIGH|MEDIUM|LOW",
+      "context": "What prompted this decision",
+      "decision": "What was decided",
+      "consequences": "What follows from this"
+    }
+  ],
+  "conventions": [
+    {
+      "id": "CN-001",
+      "title": "Short title",
+      "confidence": "HIGH|MEDIUM|LOW",
+      "scope": "project|module|file",
+      "convention": "What the convention is",
+      "examples": "Brief code example",
+      "rationale": "Why this convention exists"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "id": "AP-001",
+      "title": "Short title",
+      "confidence": "HIGH|MEDIUM|LOW",
+      "severity": "critical|warning|info",
+      "problem": "What the anti-pattern looks like",
+      "harm": "Why it is harmful",
+      "alternative": "The preferred approach"
+    }
+  ],
+  "domains": [
+    {
+      "name": "Domain Name",
+      "confidence": "HIGH|MEDIUM|LOW",
+      "responsibilities": "What this domain owns",
+      "boundaries": "Key directories and modules",
+      "dependencies": "Other domains it depends on",
+      "publicApi": "Interfaces it exposes"
+    }
+  ]
+}
+\`\`\`
+
+Be precise and factual. Only document what is verifiable in the code.
+Assign confidence levels honestly — use LOW for inferences.
+`;