id3-cli 0.9.1

package/templates/hooks/pre-commit

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+
+// src/hooks/pre-commit-entry.ts
+import { resolve } from "node:path";
+
+// src/hooks/shared.ts
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+// src/utils/ascii.ts
+function box(content, options = {}) {
+  const { title, width = 47, padding = 1 } = options;
+  const lines = content.split("\n");
+  const innerWidth = width - 2;
+  const padStr = " ".repeat(padding);
+  const result = [];
+  if (title) {
+    const titleStr = ` ${title} `;
+    const remaining = innerWidth - titleStr.length - 1;
+    result.push(`  \u250C\u2500${titleStr}${"\u2500".repeat(Math.max(0, remaining))}\u2510`);
+  } else {
+    result.push(`  \u250C${"\u2500".repeat(innerWidth)}\u2510`);
+  }
+  result.push(`  \u2502${" ".repeat(innerWidth)}\u2502`);
+  for (const line of lines) {
+    const padded = `${padStr}${line}`;
+    const spaces = innerWidth - padded.length;
+    result.push(`  \u2502${padded}${" ".repeat(Math.max(0, spaces))}\u2502`);
+  }
+  result.push(`  \u2502${" ".repeat(innerWidth)}\u2502`);
+  result.push(`  \u2514${"\u2500".repeat(innerWidth)}\u2518`);
+  return result.join("\n");
+}
+
+// src/hooks/shared.ts
+function parseGitDiff(output) {
+  if (!output.trim()) return [];
+  return output.trim().split("\n").map((line) => {
+    const [status, path] = line.split("	");
+    return { status, path };
+  }).filter((e) => e.path);
+}
+function getCachedDiff() {
+  try {
+    const output = execSync("git diff --cached --name-status", {
+      encoding: "utf-8"
+    });
+    return parseGitDiff(output);
+  } catch {
+    return [];
+  }
+}
+function getCachedFileContent(filePath) {
+  try {
+    return execSync(`git show :${filePath}`, { encoding: "utf-8" });
+  } catch {
+    return null;
+  }
+}
+function isSchemaFile(filePath, patterns) {
+  return patterns.some((pattern) => matchGlob(filePath, pattern));
+}
+function isValidationFile(filePath, patterns) {
+  return patterns.some((pattern) => matchGlob(filePath, pattern));
+}
+function matchGlob(filePath, pattern) {
+  const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${regex}$`).test(filePath) || new RegExp(`(^|/)${regex}$`).test(filePath);
+}
+async function loadHookConfig(projectRoot2) {
+  try {
+    const configPath = join(
+      projectRoot2,
+      ".claude",
+      "hooks",
+      "hook-config.json"
+    );
+    const content = await readFile(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function isSkipHooks() {
+  return process.env["IDDD_SKIP_HOOKS"] === "1";
+}
+async function logSkip(projectRoot2) {
+  const { appendFile, mkdir } = await import("node:fs/promises");
+  const logDir = join(projectRoot2, ".iddd");
+  await mkdir(logDir, { recursive: true });
+  const logPath = join(logDir, "skip-history.log");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  let commitHash = "unknown";
+  try {
+    commitHash = execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+  } catch {
+  }
+  await appendFile(logPath, `${timestamp}	${commitHash}	Hook skipped
+`);
+}
+function printBlock(title, message) {
+  console.error(box(message, { title }));
+}
+function printWarn(title, message) {
+  console.error(box(message, { title }));
+}
+
+// src/hooks/schema-drift.ts
+function analyzeSchemaChanges(diffContent, filePath) {
+  const changes = [];
+  const addedLines = diffContent.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1).trim());
+  for (const line of addedLines) {
+    const createMatch = line.match(/CREATE\s+TABLE\s+(\w+)/i);
+    if (createMatch) {
+      changes.push({
+        type: "add",
+        table: createMatch[1],
+        trivial: false,
+        description: `Table ${createMatch[1]} created`
+      });
+      continue;
+    }
+    const alterAddMatch = line.match(
+      /ALTER\s+TABLE\s+(\w+)\s+ADD\s+(?:COLUMN\s+)?(\w+)/i
+    );
+    if (alterAddMatch) {
+      changes.push({
+        type: "add",
+        table: alterAddMatch[1],
+        column: alterAddMatch[2],
+        trivial: false,
+        description: `Column ${alterAddMatch[1]}.${alterAddMatch[2]} added`
+      });
+      continue;
+    }
+    const dropMatch = line.match(/DROP\s+TABLE\s+(\w+)/i);
+    if (dropMatch) {
+      changes.push({
+        type: "drop",
+        table: dropMatch[1],
+        trivial: false,
+        description: `Table ${dropMatch[1]} dropped`
+      });
+      continue;
+    }
+    const indexMatch = line.match(/CREATE\s+(?:UNIQUE\s+)?INDEX\s+/i);
+    if (indexMatch) {
+      const tableMatch = line.match(/ON\s+(\w+)/i);
+      changes.push({
+        type: "modify",
+        table: tableMatch?.[1] ?? "unknown",
+        trivial: true,
+        description: `Index added`
+      });
+      continue;
+    }
+    const prismaModel = line.match(/^model\s+(\w+)\s*\{/);
+    if (prismaModel) {
+      changes.push({
+        type: "add",
+        table: prismaModel[1],
+        trivial: false,
+        description: `Model ${prismaModel[1]} added`
+      });
+      continue;
+    }
+    const djangoModel = line.match(/^class\s+(\w+)\(.*Model.*\)/);
+    if (djangoModel) {
+      changes.push({
+        type: "add",
+        table: djangoModel[1],
+        trivial: false,
+        description: `Model ${djangoModel[1]} added`
+      });
+      continue;
+    }
+  }
+  return changes;
+}
+async function runSchemaDrift(projectRoot2) {
+  if (isSkipHooks()) {
+    await logSkip(projectRoot2);
+    return true;
+  }
+  const config = await loadHookConfig(projectRoot2);
+  if (!config?.hooks["pre-commit"]["schema-drift"]?.enabled) {
+    return true;
+  }
+  const { monitored_patterns } = config.hooks["pre-commit"]["schema-drift"];
+  const diff = getCachedDiff();
+  const schemaFiles = diff.filter(
+    (e) => isSchemaFile(e.path, monitored_patterns)
+  );
+  if (schemaFiles.length === 0) return true;
+  const catalogModified = diff.some(
+    (e) => e.path === "specs/entity-catalog.md"
+  );
+  const allChanges = [];
+  for (const file of schemaFiles) {
+    const content = getCachedFileContent(file.path);
+    if (content) {
+      allChanges.push(...analyzeSchemaChanges(content, file.path));
+    }
+  }
+  if (allChanges.length === 0) return true;
+  const hasStructural = allChanges.some((c) => !c.trivial);
+  if (catalogModified) {
+    return true;
+  }
+  if (!hasStructural) {
+    printWarn(
+      "\u26A0\uFE0F Schema Change Detected",
+      allChanges.map((c) => c.description).join("\n") + "\n\nConsider updating specs/entity-catalog.md"
+    );
+    return true;
+  }
+  const changeList = allChanges.filter((c) => !c.trivial).map((c) => `  ${c.description}`).join("\n");
+  printBlock(
+    "\u274C Schema Drift Detected",
+    `entity-catalog.md must be updated first.
+
+${changeList}
+
+Run /id3-info-audit or manually update
+specs/entity-catalog.md`
+  );
+  return false;
+}
+
+// src/hooks/rule-check.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+var VALIDATION_PATTERNS = [
+  {
+    regex: /z\.\s*(?:object|string|number|boolean|array|enum)\s*\(/g,
+    label: "zod"
+  },
+  {
+    regex: /yup\.\s*(?:object|string|number|boolean|array)\s*\(/g,
+    label: "yup"
+  },
+  {
+    regex: /Joi\.\s*(?:object|string|number|boolean|array)\s*\(/g,
+    label: "joi"
+  },
+  { regex: /CHECK\s*\(/gi, label: "SQL CHECK" },
+  { regex: /NOT\s+NULL/gi, label: "SQL NOT NULL" },
+  { regex: /ADD\s+.*UNIQUE/gi, label: "SQL UNIQUE" },
+  { regex: /@validator\s*\(/g, label: "pydantic" },
+  { regex: /@field_validator\s*\(/g, label: "pydantic-v2" },
+  { regex: /@Valid/g, label: "java-valid" },
+  { regex: /@NotNull/g, label: "java-notnull" },
+  {
+    regex: /@Column\s*\(\s*.*nullable\s*[:=]\s*false/g,
+    label: "orm-notnull"
+  },
+  { regex: /@IsNotEmpty\s*\(/g, label: "class-validator" },
+  {
+    regex: /body\s*\(\s*['"].*['"]\s*\)\s*\.(?:not|is)/g,
+    label: "express-validator"
+  }
+];
+function detectValidationPatterns(content, filePath) {
+  const detections = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.startsWith("+") && content.includes("\n+")) {
+      continue;
+    }
+    const cleanLine = line.replace(/^\+/, "");
+    for (const { regex, label } of VALIDATION_PATTERNS) {
+      regex.lastIndex = 0;
+      if (regex.test(cleanLine)) {
+        detections.push({
+          file: filePath,
+          line: i + 1,
+          content: cleanLine.trim(),
+          pattern: label
+        });
+      }
+    }
+  }
+  return detections;
+}
+async function hasMatchingRule(projectRoot2, detection) {
+  try {
+    const rulesPath = join2(projectRoot2, "docs", "business-rules.md");
+    const rules = await readFile2(rulesPath, "utf-8");
+    return rules.includes("BR-") && rules.length > 200;
+  } catch {
+    return false;
+  }
+}
+async function runRuleCheck(projectRoot2) {
+  if (isSkipHooks()) {
+    await logSkip(projectRoot2);
+    return true;
+  }
+  const config = await loadHookConfig(projectRoot2);
+  if (!config?.hooks["pre-commit"]["rule-check"]?.enabled) {
+    return true;
+  }
+  const { validation_patterns } = config.hooks["pre-commit"]["rule-check"];
+  const diff = getCachedDiff();
+  const validationFiles = diff.filter(
+    (e) => isValidationFile(e.path, validation_patterns)
+  );
+  if (validationFiles.length === 0) return true;
+  const allDetections = [];
+  for (const file of validationFiles) {
+    const content = getCachedFileContent(file.path);
+    if (content) {
+      allDetections.push(...detectValidationPatterns(content, file.path));
+    }
+  }
+  if (allDetections.length === 0) return true;
+  for (const detection of allDetections) {
+    const matched = await hasMatchingRule(projectRoot2, detection);
+    if (!matched) {
+      printWarn(
+        "\u26A0\uFE0F New Validation Detected",
+        `File: ${detection.file}:${detection.line}
+Pattern: ${detection.pattern}
+Content: ${detection.content}
+
+No matching BR-xxx in business-rules.md
+Consider registering this rule.`
+      );
+    }
+  }
+  return true;
+}
+
+// src/hooks/pre-commit-entry.ts
+var projectRoot = resolve(".");
+async function main() {
+  const schemaDriftOk = await runSchemaDrift(projectRoot);
+  if (!schemaDriftOk) {
+    process.exit(1);
+  }
+  await runRuleCheck(projectRoot);
+}
+main().catch((err) => {
+  console.error("IDDD pre-commit hook error:", err);
+  process.exit(1);
+});

package/templates/skills/id3-design-information/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: id3-design-information
+description: >
+  Refine conceptual model into logical model. Auto-derive business rules,
+  validity constraints, and derivation rules from the information model.
+  Trigger: information structuring, model refinement, logical model, schema design,
+  design information, refine model
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+user-invocable: true
+---
+
+# Phase 2: Information Design
+
+You are the lead agent performing IDDD Phase 2. This phase refines the conceptual model produced by Phase 0/1 into a logical model. Business rules, validity constraints, and derivation rules are systematically derived from the information model.
+
+## Prerequisites
+
+Before starting, verify the following conditions:
+
+1. `specs/entity-catalog.md` exists and contains at least 2 identified entities.
+2. `specs/data-model.md` exists with a Mermaid ERD (even if preliminary).
+3. `docs/business-rules.md` exists (may be empty or partially populated from Phase 0).
+4. `steering/data-conventions.md` exists with project naming and typing conventions.
+
+If prerequisites are **not** met, respond:
+
+> "Please complete Phase 0/1 (entity identification) first. Use 'identify entities' to start."
+
+Do **not** proceed until all prerequisites are confirmed.
+
+## Procedure Overview
+
+Phase 2 consists of five sequential steps. Steps 1-3 refine the model and derive rules. Step 4 resolves ambiguities with the user. Step 5 updates all artifacts.
+
+### Step 1: Attribute Refinement
+
+For each entity in `specs/entity-catalog.md`:
+
+- Assign concrete data types (UUID, TEXT, INTEGER, TIMESTAMP, JSONB, BOOLEAN, ENUM, etc.)
+- Add constraints: NOT NULL, DEFAULT, UNIQUE, CHECK
+- Evaluate index needs (search targets, FKs, frequently filtered attributes)
+- Follow conventions defined in `steering/data-conventions.md`
+
+Key conventions to enforce:
+- PK strategy: UUID v7 by default (time-sortable)
+- All entities get `created_at` and `updated_at` timestamps
+- FK columns get automatic indexes
+- ENUM vs reference table: 3 or fewer fixed values use ENUM; more use a reference table
+- JSON columns: allowed only for frequently changing metadata; normalize if searchable
+
+### Step 2: Relationship Concretization
+
+For each relationship in the entity catalog:
+
+- Determine FK placement (which table holds the FK)
+  - 1:N relationships: FK goes on the "many" side
+  - 1:1 relationships: FK goes on the dependent/optional side
+  - N:M relationships: create a junction table with two FKs
+- Specify delete/update rules for every FK:
+  - CASCADE: child has no meaning without parent
+  - SET NULL: child can exist independently
+  - RESTRICT: prevent deletion when children exist
+- Identify junction tables for many-to-many relationships and name them using either alphabetical convention (`entity_a_entity_b`) or a domain-specific name if one exists
+- Define junction table attributes (if any beyond the two FKs, e.g., `role`, `quantity`, `start_date`)
+- Update the Mermaid ERD in `specs/data-model.md` to reflect all FK placements and junction tables
+
+### Step 3: Business Rule Auto-Derivation
+
+Systematically scan the refined model and derive rules. Number each rule as BR-001, BR-002, etc.
+
+**Derivation patterns:**
+
+| Model Element | Rule Type | Example |
+|---|---|---|
+| NOT NULL constraint | Required field | "BR-001: User.email is required" |
+| UNIQUE constraint | Uniqueness | "BR-002: User.email must be unique" |
+| FK + CASCADE | Cascade delete | "BR-003: Deleting a Project deletes all Tasks" |
+| FK + RESTRICT | Referential guard | "BR-004: Cannot delete Category with existing Products" |
+| ENUM values | Validity domain | "BR-005: Order.status must be one of: draft, confirmed, shipped, delivered" |
+| State transitions | Transition paths | "BR-006: Order can only transition draft->confirmed->shipped->delivered" |
+| Derived attributes | Computation | "BR-007: Order.total = SUM(LineItem.subtotal)" |
+| CHECK constraints | Range/format | "BR-008: Product.price must be >= 0" |
+
+For each rule, record: entity, type (constraint / derivation / transition / validity), description, enforcement location (DB constraint / application logic / both), and implementation approach.
+
+**Rule numbering:** Continue from the last BR-xxx number if Phase 0/1 already defined rules. Do not renumber existing rules.
+
+**Cross-entity rules:** Some rules span multiple entities (cascade constraints, aggregate rules, cross-reference rules). These require explicit documentation since they cannot be enforced by a single column constraint.
+
+**Conflict resolution:** If an auto-derived rule conflicts with an existing rule from Phase 0/1, flag the conflict to the user, present both versions, and let the user decide. Record unresolved conflicts in `docs/info-debt.md`.
+
+**For detailed step-by-step procedures, see:** `references/phase2-procedure.md`
+
+### Step 4: Design Decision Questions
+
+Present questions to the user for decisions that cannot be auto-derived:
+
+1. **Large data storage** -- inline vs external storage (S3, etc.) for binary/large text fields
+2. **Soft delete scope** -- which entities use `deleted_at` pattern vs hard delete
+3. **Multi-tenancy** -- tenant isolation strategy (row-level, schema-level, or none)
+4. **Audit trail** -- which entities need history tracking (who changed what, when)
+5. **Project-specific decisions** -- any domain-specific architectural choices
+
+Record each decision in `specs/data-model.md` under "Design Decisions" with an ID (D-01, D-02, etc.), topic, choice, rationale, and date. Apply decisions immediately by updating the entity catalog: add `deleted_at` columns where soft delete applies, add `tenant_id` where multi-tenancy applies, add audit columns where history tracking is needed.
+
+Skip question categories that are clearly not applicable to the project. For example, skip multi-tenancy for single-tenant applications, skip audit trail for prototype projects.
+
+### Step 5: Artifact Updates
+
+Update artifacts in this specific order to maintain consistency:
+
+1. **`specs/entity-catalog.md`** -- Add all refined attributes with concrete data types, constraints, indexes. Verify every entity has: all attributes typed, NOT NULL/DEFAULT/UNIQUE specified, `created_at`/`updated_at` present, soft delete and tenant columns added per design decisions, all relationships listing FK column, cardinality, and delete rule.
+
+2. **`specs/data-model.md`** -- Update the Mermaid ERD to reflect all entities, attributes, relationships, and junction tables. Populate the "Index Strategy" section. Populate the "Design Decisions" table with all D-xx entries.
+
+3. **`docs/business-rules.md`** -- Add all derived rules (BR-001+) with full metadata: entity, type, description, enforcement location, and implementation approach. Ensure no duplicate or conflicting rules exist.
+
+## Artifacts Produced
+
+Upon completion, the following files will be created or updated:
+
+| File | Status | Content |
+|---|---|---|
+| `specs/entity-catalog.md` | Updated | Data types, constraints, indexes added |
+| `specs/data-model.md` | Updated | ERD, FK details, junction tables, design decisions |
+| `docs/business-rules.md` | Updated | All derived business rules (BR-xxx) |
+| `.iddd/preview/erd-phase2.html` | Created | ERD preview |
+
+## Preview Integration
+
+After completing all five steps, generate visual previews for user review:
+
+1. **Generate ERD preview:** Render the finalized Mermaid ERD from `specs/data-model.md` into `.iddd/preview/erd-phase2.html`. The HTML file should embed the Mermaid library and render the ERD diagram with full entity details, relationships, and cardinality notation.
+
+2. **Start preview server** with the ERD file available so the user can review in the browser. The server serves files from the `.iddd/preview/` directory.
+
+Use `/id3-preview` to manually start or restart the preview server at any time.
+
+## Version Header and Changelog
+
+Upon Phase 2 completion, update YAML frontmatter in `specs/entity-catalog.md` and `specs/data-model.md`:
+
+```yaml
+---
+version: "1.0"
+last_verified: "YYYY-MM-DD"
+phase: "Phase 2 Complete"
+entity_count: N
+rule_count: N
+audit_status: "clean"
+---
+```
+
+Add an entry to `docs/model-changelog.md` following Keep a Changelog format:
+
+```markdown
+## [1.0] -- YYYY-MM-DD
+### Phase 2 Complete
+- N entities: logical model finalized
+- M business rules derived
+- Design decisions: D-01 (...), D-02 (...), ...
+```
+
+## Completion Message
+
+When all steps are finished, display:
+
+> "Logical model finalized. Phase 2 derived N business rules. Proceed to Phase 2.5 (/id3-design-ui) for UI design and implementation."
+
+Replace N with actual count from the session.