@surfaice/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 surfaiceai
+
+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,45 @@
+# @surfaice/cli
+
+CLI tool for managing Surfaice UI manifests — export, check drift, and diff changes.
+
+## Install
+
+```bash
+npm install -g @surfaice/cli
+# or use without installing:
+npx @surfaice/cli
+```
+
+## Commands
+
+### `surfaice export`
+Fetch routes from a running app and save `.surfaice.md` files.
+
+```bash
+surfaice export -u http://localhost:3000 -r /settings /dashboard -o ./surfaice/
+```
+
+### `surfaice check`
+Compare committed `.surfaice.md` files against the live app. Exit code 1 on drift — CI-ready.
+
+```bash
+surfaice check -u http://localhost:3000 -d ./surfaice/
+# ✅ /settings — 6 elements match
+# ❌ /dashboard — DRIFT: 1 added, 1 changed
+```
+
+### `surfaice diff`
+Show human-readable or JSON diff between committed and live.
+
+```bash
+surfaice diff -u http://localhost:3000 -d ./surfaice/
+surfaice diff -u http://localhost:3000 -d ./surfaice/ --json
+```
+
+## CI Integration
+
+```yaml
+# .github/workflows/surfaice.yml
+- name: Check for UI drift
+  run: surfaice check -u ${{ env.APP_URL }} -d ./surfaice/
+```

package/dist/commands/check.d.ts

@@ -0,0 +1,11 @@
+export interface CheckOptions {
+    /** Directory containing committed .surfaice.md files */
+    dir: string;
+    /** Base URL of the running app */
+    baseUrl: string;
+}
+/**
+ * Compare committed .surfaice.md files against the live app.
+ * Returns 0 on success (no drift), 1 on any failures or drift.
+ */
+export declare function checkCommand(options: CheckOptions): Promise<number>;

package/dist/commands/check.js

@@ -0,0 +1,51 @@
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { parse } from '@surfaice/format';
+import { diff } from '@surfaice/differ';
+/**
+ * Compare committed .surfaice.md files against the live app.
+ * Returns 0 on success (no drift), 1 on any failures or drift.
+ */
+export async function checkCommand(options) {
+    const files = readdirSync(options.dir)
+        .filter((f) => f.endsWith('.surfaice.md'));
+    let failures = 0;
+    for (const file of files) {
+        const committed = readFileSync(join(options.dir, file), 'utf-8');
+        const expected = parse(committed);
+        const route = expected.route;
+        let response;
+        try {
+            response = await fetch(new URL(route, options.baseUrl).toString(), {
+                headers: { 'Accept': 'text/surfaice' },
+            });
+        }
+        catch (err) {
+            console.error(`❌ ${route} — Network error: ${String(err)}`);
+            failures++;
+            continue;
+        }
+        if (!response.ok) {
+            console.error(`❌ ${route} — ${response.status} ${response.statusText}`);
+            failures++;
+            continue;
+        }
+        const live = parse(await response.text());
+        const result = diff(expected, live);
+        if (result.status === 'match') {
+            const elementCount = expected.sections.reduce((n, s) => n + s.elements.length, 0);
+            console.log(`✅ ${route} — ${elementCount} elements match`);
+        }
+        else {
+            console.log(`❌ ${route} — DRIFT: ${result.summary}`);
+            for (const a of result.added)
+                console.log(`   + [${a.id}] ${a.type} "${a.label}"`);
+            for (const r of result.removed)
+                console.log(`   - [${r.id}] ${r.type} "${r.label}"`);
+            for (const c of result.changed)
+                console.log(`   ~ [${c.id}] ${c.field}: "${c.expected}" → "${c.actual}"`);
+            failures++;
+        }
+    }
+    return failures > 0 ? 1 : 0;
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,15 @@
+import type { SurfaiceDiff } from '@surfaice/differ';
+export interface DiffOptions {
+    dir: string;
+    baseUrl: string;
+    /** Output as JSON instead of human-readable text */
+    json?: boolean;
+}
+export interface DiffResult extends SurfaiceDiff {
+    file: string;
+}
+/**
+ * Show structural diff between committed .surfaice.md files and the live app.
+ * Returns array of diff results (one per file).
+ */
+export declare function diffCommand(options: DiffOptions): Promise<DiffResult[]>;

package/dist/commands/diff.js

@@ -0,0 +1,50 @@
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { parse } from '@surfaice/format';
+import { diff } from '@surfaice/differ';
+/**
+ * Show structural diff between committed .surfaice.md files and the live app.
+ * Returns array of diff results (one per file).
+ */
+export async function diffCommand(options) {
+    const files = readdirSync(options.dir)
+        .filter((f) => f.endsWith('.surfaice.md'));
+    const results = [];
+    for (const file of files) {
+        const committed = readFileSync(join(options.dir, file), 'utf-8');
+        const expected = parse(committed);
+        const route = expected.route;
+        let response;
+        try {
+            response = await fetch(new URL(route, options.baseUrl).toString(), {
+                headers: { 'Accept': 'text/surfaice' },
+            });
+        }
+        catch (err) {
+            console.error(`❌ ${route} — Network error: ${String(err)}`);
+            continue;
+        }
+        if (!response.ok) {
+            console.error(`❌ ${route} — ${response.status} ${response.statusText}`);
+            continue;
+        }
+        const live = parse(await response.text());
+        const result = diff(expected, live);
+        results.push({ ...result, file });
+        if (options.json)
+            continue; // collect silently for JSON output
+        // Human-readable output
+        const icon = result.status === 'match' ? '✅' : '❌';
+        console.log(`${icon} ${route} — ${result.summary}`);
+        for (const a of result.added)
+            console.log(`   + [${a.id}] ${a.type} "${a.label}" (${a.section})`);
+        for (const r of result.removed)
+            console.log(`   - [${r.id}] ${r.type} "${r.label}" (${r.section})`);
+        for (const c of result.changed)
+            console.log(`   ~ [${c.id}].${c.field}: "${c.expected}" → "${c.actual}"`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+    }
+    return results;
+}

package/dist/commands/export.d.ts

@@ -0,0 +1,11 @@
+export interface ExportOptions {
+    baseUrl: string;
+    routes: string[];
+    /** Output directory. Default: 'surfaice/' */
+    outDir: string;
+}
+/**
+ * Fetch each route with Accept: text/surfaice and write .surfaice.md files.
+ */
+export declare function exportCommand(options: ExportOptions): Promise<void>;
+export declare function routeToFilename(route: string): string;

package/dist/commands/export.js

@@ -0,0 +1,36 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+/**
+ * Fetch each route with Accept: text/surfaice and write .surfaice.md files.
+ */
+export async function exportCommand(options) {
+    mkdirSync(options.outDir, { recursive: true });
+    for (const route of options.routes) {
+        const url = new URL(route, options.baseUrl).toString();
+        let response;
+        try {
+            response = await fetch(url, {
+                headers: { 'Accept': 'text/surfaice' },
+            });
+        }
+        catch (err) {
+            console.error(`❌ ${route} — Network error: ${String(err)}`);
+            continue;
+        }
+        if (!response.ok) {
+            console.error(`❌ ${route} — ${response.status} ${response.statusText}`);
+            continue;
+        }
+        const markdown = await response.text();
+        const filename = routeToFilename(route);
+        const filepath = join(options.outDir, filename);
+        mkdirSync(dirname(filepath), { recursive: true });
+        writeFileSync(filepath, markdown);
+        console.log(`✅ ${route} → ${filepath}`);
+    }
+}
+export function routeToFilename(route) {
+    if (route === '/')
+        return 'index.surfaice.md';
+    return `${route.slice(1).replace(/\//g, '-')}.surfaice.md`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { exportCommand } from './commands/export.js';
+import { checkCommand } from './commands/check.js';
+import { diffCommand } from './commands/diff.js';
+const program = new Command()
+    .name('surfaice')
+    .description('Surfaice CLI — manage UI manifests')
+    .version('0.0.1');
+program
+    .command('export')
+    .description('Export .surfaice.md files from a running app')
+    .requiredOption('-u, --url <url>', 'Base URL of the running app')
+    .option('-r, --routes <routes...>', 'Routes to export', ['/'])
+    .option('-o, --out <dir>', 'Output directory', 'surfaice/')
+    .action(async (opts) => {
+    await exportCommand({ baseUrl: opts.url, routes: opts.routes, outDir: opts.out });
+});
+program
+    .command('check')
+    .description('Check committed .surfaice.md files against live app')
+    .requiredOption('-u, --url <url>', 'Base URL of the running app')
+    .option('-d, --dir <dir>', 'Directory with .surfaice.md files', 'surfaice/')
+    .action(async (opts) => {
+    const exitCode = await checkCommand({ dir: opts.dir, baseUrl: opts.url });
+    process.exit(exitCode);
+});
+program
+    .command('diff')
+    .description('Show drift between committed and live UI')
+    .requiredOption('-u, --url <url>', 'Base URL of the running app')
+    .option('-d, --dir <dir>', 'Directory with .surfaice.md files', 'surfaice/')
+    .option('--json', 'Output as JSON', false)
+    .action(async (opts) => {
+    await diffCommand({ dir: opts.dir, baseUrl: opts.url, json: opts.json });
+});
+program.parse();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@surfaice/cli",
+  "version": "0.0.1",
+  "description": "Surfaice CLI — export, check, and diff UI manifests",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "surfaice": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/surfaiceai/surfaice",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@surfaice/differ": "0.0.1",
+    "@surfaice/format": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  }
+}