@trineui/cli 0.1.0-beta.1

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@trineui/cli",
+  "version": "0.1.0-beta.1",
+  "description": "Trine CLI — add, diff, sync, and eject Angular UI components",
+  "keywords": ["angular", "cli", "trine", "ui-components", "code-generation"],
+  "author": "Chatchawan Phrueksawan <pete.chatchawan@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/petechatchawan/forge.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://docs.trine-ui.dev/cli/reference",
+  "bugs": "https://github.com/petechatchawan/forge/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "trine": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outdir=dist --external:commander --external:diff --external:handlebars --external:@inquirer/* --external:node:stream --external:node:readline --external:node:events --external:node:util --external:ts-morph"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "commander": "^14.0.3",
+    "diff": "^8.0.3",
+    "handlebars": "^4.7.8",
+    "ts-morph": "^27.0.2"
+  },
+  "devDependencies": {
+    "@types/diff": "^8.0.0",
+    "@types/handlebars": "^4.1.0",
+    "esbuild": "^0.27.4",
+    "tsx": "^4.21.0",
+    "vitest": "^4.1.0"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,101 @@
+import { Command } from 'commander';
+import {
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+} from 'fs';
+import { resolve, join } from 'path';
+import { computeNormalizedHash } from '../utils/hash.js';
+import { readManifest, writeManifest } from '../utils/manifest.js';
+import { renderTemplate } from '../utils/template.js';
+import type { ComponentEntry, TrineManifest } from '../types/manifest.js';
+
+const ENGINE_VERSION = '0.1.0';
+const BLUEPRINT_SCHEMA_VERSION = '1.0.0';
+
+export const addCommand = new Command('add')
+  .argument('<component>', 'Component name (e.g. button)')
+  .option('--force', 'Overwrite existing blueprint (skin is NEVER overwritten)')
+  .option(
+    '--dir <path>',
+    'Output directory relative to project root',
+    'src/components/ui'
+  )
+  .description('Add a component blueprint + skin to your project')
+  .action(async (component: string, options: { force?: boolean; dir: string }) => {
+    const projectRoot = process.cwd();
+    const componentDir = resolve(projectRoot, options.dir, component);
+    const blueprintPath = join(componentDir, `${component}.blueprint.ts`);
+    const skinPath = join(componentDir, `${component}.skin.ts`);
+
+    if (!isSupportedComponent(component)) {
+      console.error(`✗ Unknown component: "${component}"`);
+      console.error(`  Supported: button, input, dialog, checkbox, select`);
+      process.exit(1);
+    }
+
+    if (existsSync(blueprintPath) && !options.force) {
+      console.error(`✗ ${component}.blueprint.ts already exists`);
+      console.error('');
+      console.error(`  To overwrite blueprint (skin will NOT be touched):`);
+      console.error(`    trine add ${component} --force`);
+      process.exit(1);
+    }
+
+    const ctx = {
+      engineVersion: ENGINE_VERSION,
+      blueprintSchemaVersion: BLUEPRINT_SCHEMA_VERSION,
+    };
+
+    const blueprintContent = renderTemplate(`${component}.blueprint.ts.hbs`, ctx);
+    const skinContent = renderTemplate(`${component}.skin.ts.hbs`, ctx);
+
+    mkdirSync(componentDir, { recursive: true });
+
+    writeFileSync(blueprintPath, blueprintContent, 'utf-8');
+    console.log(`  ✓ ${options.dir}/${component}/${component}.blueprint.ts`);
+
+    if (!existsSync(skinPath)) {
+      writeFileSync(skinPath, skinContent, 'utf-8');
+      console.log(`  ✓ ${options.dir}/${component}/${component}.skin.ts`);
+    } else {
+      console.log(`  ~ ${options.dir}/${component}/${component}.skin.ts (kept — user-owned)`);
+    }
+
+    const existingManifest = readManifest(projectRoot);
+    const manifest: TrineManifest = existingManifest ?? {
+      'trine-spec': '1.0',
+      components: {},
+    };
+
+    const blueprintHash = computeNormalizedHash(blueprintContent);
+
+    const entry: ComponentEntry = {
+      'engine-version': ENGINE_VERSION,
+      'blueprint-schema-version': BLUEPRINT_SCHEMA_VERSION,
+      'blueprint-hash': blueprintHash,
+      'blueprint-modified': false,
+      'synced-at': new Date().toISOString(),
+      'sync-model': 'normalized-text-v0.1',
+      'output-dir': options.dir,
+    };
+
+    manifest.components[component] = entry;
+    writeManifest(manifest, projectRoot);
+    console.log(`  ✓ .trine/manifest.json`);
+
+    console.log('');
+    console.log(`✓ trine add ${component} complete`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log(`    Import ${capitalize(component)}Component in your module/component`);
+    console.log(`    Run: trine diff ${component}   — check for upstream changes`);
+  });
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function isSupportedComponent(name: string): boolean {
+  return ['button', 'input', 'dialog', 'checkbox', 'select'].includes(name);
+}

package/src/commands/diff.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { computeNormalizedHash } from '../utils/hash.js';
+
+describe('hash normalization (Gate G1)', () => {
+  it('same content → same hash', () => {
+    const content = `import { Component } from '@angular/core';
+@Component({ selector: 'ui-button' })`;
+    expect(computeNormalizedHash(content)).toBe(computeNormalizedHash(content));
+  });
+
+  it('prettier-formatted single quotes → double quotes → same hash', () => {
+    const original = `import { Component } from '@angular/core';`;
+    const prettified = `import { Component } from "@angular/core";`;
+    expect(computeNormalizedHash(original)).toBe(computeNormalizedHash(prettified));
+  });
+
+  it('prettier multi-line → single line → same hash', () => {
+    const original = `@Component({
+  selector: 'ui-button',
+  standalone: true
+})`;
+    const prettified = `@Component({ selector: 'ui-button', standalone: true })`;
+    expect(computeNormalizedHash(original)).toBe(computeNormalizedHash(prettified));
+  });
+
+  it('prettier arrays with/without trailing comma → same hash', () => {
+    const noTrailing = `@Component({ inputs: ['a', 'b'] })`;
+    const withTrailing = `@Component({ inputs: ['a', 'b',] })`;
+    expect(computeNormalizedHash(noTrailing)).toBe(computeNormalizedHash(withTrailing));
+  });
+
+  it('prettier object spacing variations → same hash', () => {
+    const tight = `@Component({selector:'ui-button',standalone:true})`;
+    const spaced = `@Component({ selector: 'ui-button', standalone: true })`;
+    const multiline = `@Component({
+  selector: 'ui-button',
+  standalone: true
+})`;
+    const h1 = computeNormalizedHash(tight);
+    expect(computeNormalizedHash(spaced)).toBe(h1);
+    expect(computeNormalizedHash(multiline)).toBe(h1);
+  });
+
+  it('structural change → different hash', () => {
+    const v1 = `@Component({ selector: 'ui-button' })`;
+    const v2 = `@Component({ selector: 'ui-btn' })`;
+    expect(computeNormalizedHash(v1)).not.toBe(computeNormalizedHash(v2));
+  });
+
+  it('import order different → same hash (sorted)', () => {
+    const order1 = `import { A } from 'x';import { B } from 'y';`;
+    const order2 = `import { B } from 'y';import { A } from 'x';`;
+    expect(computeNormalizedHash(order1)).toBe(computeNormalizedHash(order2));
+  });
+});

package/src/commands/diff.ts

@@ -0,0 +1,104 @@
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { createTwoFilesPatch } from 'diff';
+import { computeNormalizedHash } from '../utils/hash.js';
+import { readManifest } from '../utils/manifest.js';
+import { renderTemplate } from '../utils/template.js';
+
+export const diffCommand = new Command('diff')
+  .argument('<component>', 'Component name (e.g. button)')
+  .option('--no-color', 'Disable colored output')
+  .description('Show upstream changes since last sync (read-only, no files changed)')
+  .action(async (component: string, _options: { noColor?: boolean }) => {
+    const projectRoot = process.cwd();
+
+    const manifest = readManifest(projectRoot);
+    if (!manifest?.components[component]) {
+      console.error(`✗ "${component}" not found in manifest`);
+      console.error(`  Run: trine add ${component}`);
+      process.exit(1);
+    }
+
+    const entry = manifest.components[component];
+
+    const blueprintPath = resolve(
+      projectRoot,
+      entry['output-dir'],
+      component,
+      `${component}.blueprint.ts`
+    );
+
+    if (!existsSync(blueprintPath)) {
+      console.error(`✗ Blueprint file not found: ${blueprintPath}`);
+      console.error(`  Run: trine add ${component}`);
+      process.exit(1);
+    }
+
+    const currentContent = readFileSync(blueprintPath, 'utf-8');
+    const currentHash = computeNormalizedHash(currentContent);
+    const manifestHash = entry['blueprint-hash'];
+    const isLocalModified = currentHash !== manifestHash;
+
+    const upstreamContent = renderTemplate(`${component}.blueprint.ts.hbs`, {
+      engineVersion: entry['engine-version'],
+      blueprintSchemaVersion: entry['blueprint-schema-version'],
+    });
+    const upstreamHash = computeNormalizedHash(upstreamContent);
+    const hasUpstream = upstreamHash !== manifestHash;
+
+    const safeToSync = !isLocalModified && hasUpstream;
+
+    console.log('');
+    console.log(`${component} blueprint:`);
+    console.log(
+      `  local status:    ${
+        isLocalModified
+          ? '⚠ modified (local changes detected)'
+          : '✓ clean (unmodified)'
+      }`
+    );
+    console.log(
+      `  upstream status: ${
+        hasUpstream
+          ? `updates available (engine: ${entry['engine-version']} → check changelog)`
+          : '✓ up to date'
+      }`
+    );
+    console.log(
+      `  safe to sync:    ${
+        safeToSync
+          ? 'yes — run: trine sync ' + component
+          : isLocalModified
+            ? 'no — run: trine sync ' + component + ' --interactive'
+            : 'nothing to sync'
+      }`
+    );
+
+    if (hasUpstream) {
+      console.log('');
+      console.log('--- upstream changes ---');
+
+      const patch = createTwoFilesPatch(
+        `${component}.blueprint.ts (current)`,
+        `${component}.blueprint.ts (upstream)`,
+        currentContent,
+        upstreamContent,
+        '',
+        '',
+        { context: 3 }
+      );
+
+      const lines = patch.split('\n').slice(0, 50);
+      console.log(lines.join('\n'));
+
+      if (patch.split('\n').length > 50) {
+        console.log('  ... (truncated, use trine sync --interactive for full diff)');
+      }
+    }
+
+    console.log('');
+    console.log(`${component} skin:`);
+    console.log(`  (no upstream — user-owned, never synced)`);
+    console.log('');
+  });

package/src/commands/eject.ts

@@ -0,0 +1,95 @@
+import { confirm } from "@inquirer/prompts";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { Command } from "commander";
+import { mergeForEject } from "../utils/eject-merger.js";
+import { readManifest, writeManifest } from "../utils/manifest.js";
+
+export const ejectCommand = new Command("eject")
+  .argument("<component>", "Component name to eject (e.g. button)")
+  .option("--yes", "Skip confirmation prompt")
+  .description(
+    "Merge blueprint + skin into a standalone component. One-way — no re-attach."
+  )
+  .action(
+    async (component: string, options: { yes?: boolean }) => {
+      const projectRoot = process.cwd();
+      const manifest = readManifest(projectRoot);
+
+      if (!manifest?.components[component]) {
+        console.error(`✗ "${component}" not found in manifest`);
+        process.exit(1);
+      }
+
+      const entry = manifest.components[component];
+      const outputDir = resolve(projectRoot, entry["output-dir"], component);
+      const blueprintPath = resolve(
+        outputDir,
+        `${component}.blueprint.ts`
+      );
+      const skinPath = resolve(outputDir, `${component}.skin.ts`);
+      const outputPath = resolve(outputDir, `${component}.component.ts`);
+
+      if (!existsSync(blueprintPath) || !existsSync(skinPath)) {
+        console.error(
+          `✗ Blueprint or skin file not found for "${component}"`
+        );
+        process.exit(1);
+      }
+
+      console.log("");
+      console.log("⚠️  trine eject — THIS IS ONE-WAY");
+      console.log("");
+      console.log(`  Component:  ${component}`);
+      console.log(`  Output:     ${component}.component.ts`);
+      console.log(
+        `  Removes:    ${component}.blueprint.ts + ${component}.skin.ts`
+      );
+      console.log(`  Manifest:   ${component} entry will be deleted`);
+      console.log("");
+      console.log("  Warning:    This cannot be undone.");
+      console.log(
+        "              The component will no longer receive upstream updates."
+      );
+      console.log("");
+
+      const confirmed =
+        options.yes ||
+        (await confirm({
+          message: `Eject "${component}"? This is permanent.`,
+          default: false,
+        }));
+
+      if (!confirmed) {
+        console.log("Aborted.");
+        return;
+      }
+
+      const blueprintContent = readFileSync(blueprintPath, "utf-8");
+      const skinContent = readFileSync(skinPath, "utf-8");
+
+      const merged = mergeForEject(
+        component,
+        blueprintContent,
+        skinContent
+      );
+
+      writeFileSync(outputPath, merged, "utf-8");
+      console.log(`  ✓ ${component}.component.ts written`);
+
+      unlinkSync(blueprintPath);
+      unlinkSync(skinPath);
+      console.log(`  ✓ ${component}.blueprint.ts removed`);
+      console.log(`  ✓ ${component}.skin.ts removed`);
+
+      delete manifest.components[component];
+      writeManifest(manifest, projectRoot);
+      console.log(`  ✓ manifest.json updated`);
+
+      console.log("");
+      console.log(`✓ ${component} ejected.`);
+      console.log(
+        `  Edit ${component}.component.ts directly going forward.`
+      );
+    }
+  );

package/src/commands/init.ts

@@ -0,0 +1,92 @@
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { computeNormalizedHash } from '../utils/hash.js';
+import { readManifest, writeManifest } from '../utils/manifest.js';
+import type { ComponentEntry, TrineManifest } from '../types/manifest.js';
+
+const SUPPORTED_COMPONENTS = ['button', 'input', 'dialog', 'checkbox', 'select'];
+
+export const initCommand = new Command('init')
+  .description('Scan project and reconstruct manifest.json from existing blueprint files')
+  .action(async () => {
+    const projectRoot = process.cwd();
+
+    const manifest = readManifest(projectRoot);
+    if (manifest) {
+      console.log('✓ .trine/manifest.json already exists');
+      console.log('  No need to run trine init.');
+      console.log('');
+      console.log('  To check sync status, run: trine diff <component>');
+      return;
+    }
+
+    console.log('Scanning for blueprint files...');
+    console.log('');
+
+    const foundComponents: { name: string; path: string; hash: string }[] = [];
+    const scanDirs = ['src/components/ui', 'components/ui'];
+
+    for (const dir of scanDirs) {
+      const basePath = resolve(projectRoot, dir);
+      if (!existsSync(basePath)) continue;
+
+      for (const component of SUPPORTED_COMPONENTS) {
+        const blueprintPath = join(basePath, component, `${component}.blueprint.ts`);
+        if (existsSync(blueprintPath)) {
+          try {
+            const content = readFileSync(blueprintPath, 'utf-8');
+            const hash = computeNormalizedHash(content);
+            foundComponents.push({ name: component, path: blueprintPath, hash });
+            console.log(`  ✓ Found: ${dir}/${component}/${component}.blueprint.ts`);
+          } catch {
+            console.log(`  ✗ Error reading: ${dir}/${component}/${component}.blueprint.ts`);
+          }
+        }
+      }
+    }
+
+    if (foundComponents.length === 0) {
+      console.log('No blueprint files found.');
+      console.log('');
+      console.log('  To add a component, run:');
+      console.log('    trine add <component>');
+      console.log('');
+      console.log('  Supported components: button, input, dialog, checkbox, select');
+      return;
+    }
+
+    console.log('');
+    console.log(`Found ${foundComponents.length} blueprint file(s)`);
+    console.log('');
+
+    const newManifest: TrineManifest = {
+      'trine-spec': '1.0',
+      components: {},
+    };
+
+    for (const { name, hash } of foundComponents) {
+      const entry: ComponentEntry = {
+        'engine-version': '0.1.0',
+        'blueprint-schema-version': '1.0.0',
+        'blueprint-hash': hash,
+        'blueprint-modified': true,
+        'synced-at': new Date().toISOString(),
+        'sync-model': 'normalized-text-v0.1',
+        'output-dir': 'src/components/ui',
+      };
+      newManifest.components[name] = entry;
+    }
+
+    writeManifest(newManifest, projectRoot);
+
+    console.log('✓ Created .trine/manifest.json');
+    console.log('');
+    console.log('⚠ Warning: blueprint-modified is set to true for all components.');
+    console.log('  This is conservative — run trine diff <component> to verify sync state.');
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    trine diff button   — check button sync status');
+    console.log('    trine diff input    — check input sync status');
+    console.log('    ...');
+  });

package/src/commands/sync-interactive.ts

@@ -0,0 +1,108 @@
+import { createTwoFilesPatch, parsePatch } from "diff";
+import { select } from "@inquirer/prompts";
+import { writeFileSync } from "fs";
+import { computeNormalizedHash } from "../utils/hash.js";
+import type { TrineManifest } from "../types/manifest.js";
+
+interface Hunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+}
+
+export async function runInteractiveSync(
+  component: string,
+  currentContent: string,
+  upstreamContent: string,
+  blueprintPath: string,
+  manifest: TrineManifest
+): Promise<"merged" | "aborted"> {
+  const patch = createTwoFilesPatch(
+    `${component}.blueprint.ts (yours)`,
+    `${component}.blueprint.ts (upstream)`,
+    currentContent,
+    upstreamContent,
+    "",
+    "",
+    { context: 3 }
+  );
+
+  const parsed = parsePatch(patch);
+  const hunks: Hunk[] =
+    parsed.length > 0 && "hunks" in parsed[0]
+      ? (parsed[0] as unknown as { hunks: Hunk[] }).hunks
+      : [];
+
+  if (hunks.length === 0) {
+    console.log("✓ No differences found.");
+    return "merged";
+  }
+
+  console.log(
+    `\nBlueprint has local changes. Upstream has ${hunks.length} changed hunk(s).\n`
+  );
+
+  const lines = currentContent.split("\n");
+
+  for (let i = 0; i < hunks.length; i++) {
+    const hunk = hunks[i];
+    console.log(`--- Hunk ${i + 1}/${hunks.length} ---`);
+    hunk.lines.forEach((line: string) => {
+      if (line.startsWith("+"))
+        console.log(`  upstream: ${line.slice(1)}`);
+      else if (line.startsWith("-"))
+        console.log(`  yours:    ${line.slice(1)}`);
+    });
+    console.log("");
+
+    const choice = await select({
+      message: "What do you want to do with this hunk?",
+      choices: [
+        {
+          name: "(k) Keep mine",
+          value: "keep",
+          description: "Keep your local version of this hunk",
+        },
+        {
+          name: "(u) Take upstream",
+          value: "upstream",
+          description: "Replace with upstream version",
+        },
+        {
+          name: "(s) Skip (keep mine)",
+          value: "skip",
+          description: "Skip this hunk, keep your version",
+        },
+      ],
+    });
+
+    if (choice === "upstream") {
+      applyHunk(lines, hunk, upstreamContent.split("\n"));
+    }
+  }
+
+  const mergedContent = lines.join("\n");
+  writeFileSync(blueprintPath, mergedContent, "utf-8");
+
+  manifest.components[component]["blueprint-hash"] =
+    computeNormalizedHash(mergedContent);
+  manifest.components[component]["blueprint-modified"] = false;
+  manifest.components[component]["synced-at"] = new Date().toISOString();
+
+  console.log("\n✓ Merged. Writing blueprint...");
+  return "merged";
+}
+
+function applyHunk(
+  lines: string[],
+  hunk: Hunk,
+  upstreamLines: string[]
+): void {
+  const start = hunk.oldStart - 1;
+  const end = start + hunk.oldLines;
+
+  const upstreamSection = upstreamLines.slice(start, end);
+  lines.splice(start, hunk.oldLines, ...upstreamSection);
+}

package/src/commands/sync.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { computeNormalizedHash } from '../utils/hash.js';
+
+describe('sync logic', () => {
+  it('same normalized hash → "untouched" path selected', () => {
+    const content = `@Component({ selector: 'ui-button' })`;
+    const hash1 = computeNormalizedHash(content);
+    const hash2 = computeNormalizedHash(content);
+    expect(hash1).toBe(hash2);
+  });
+
+  it('different hash → "modified" path selected (dirty detection correct)', () => {
+    const v1 = `@Component({ selector: 'ui-button' })`;
+    const v2 = `@Component({ selector: 'ui-btn' })`;
+    expect(computeNormalizedHash(v1)).not.toBe(computeNormalizedHash(v2));
+  });
+
+  it('skin content identical before and after sync (skin safety invariant)', () => {
+    const skinBefore = `@Injectable() export class ButtonSkin { classes = 'btn'; }`;
+    const skinAfter = skinBefore;
+    expect(skinBefore).toBe(skinAfter);
+  });
+
+  it('comment changes do not affect hash (normalized)', () => {
+    const withComment = `@Component({ selector: 'ui-button' }) // comment`;
+    const withoutComment = `@Component({ selector: 'ui-button' })`;
+    expect(computeNormalizedHash(withComment)).toBe(computeNormalizedHash(withoutComment));
+  });
+
+  it('upstream version change creates different hash', () => {
+    const v1 = `export class ButtonComponent { protected engine = inject(ButtonEngine); }`;
+    const v2 = `export class ButtonComponent { static readonly version = '0.2.0'; protected engine = inject(ButtonEngine); }`;
+    expect(computeNormalizedHash(v1)).not.toBe(computeNormalizedHash(v2));
+  });
+});