@surfaice/action 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,64 @@
+# @surfaice/action
+
+GitHub Action for detecting UI drift using Surfaice — automatically catch when your live UI diverges from committed `.surfaice.md` manifests.
+
+## Usage
+
+```yaml
+# .github/workflows/ui-drift.yml
+name: UI Drift Check
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  surfaice:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Start your app (or use a preview URL)
+      - name: Start app
+        run: pnpm dev &
+        
+      - name: Wait for app
+        run: npx wait-on http://localhost:3000
+
+      - name: Check for UI drift
+        uses: surfaiceai/surfaice/packages/action@main
+        with:
+          base-url: 'http://localhost:3000'
+          surfaice-dir: 'surfaice/'
+          fail-on-drift: 'true'
+```
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `base-url` | ✅ | — | Base URL of the running app |
+| `surfaice-dir` | | `surfaice/` | Directory with `.surfaice.md` files |
+| `fail-on-drift` | | `true` | Fail the action if drift is detected |
+| `output-format` | | `text` | Output format: `text` or `json` |
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `drift-detected` | `"true"` or `"false"` |
+| `drift-summary` | Human-readable summary of drift |
+| `diff-json` | JSON-encoded diff results |
+
+## Workflow with Surfaice CLI
+
+```yaml
+- name: Export UI manifests
+  run: npx @surfaice/cli export -u http://localhost:3000 -r /settings /dashboard
+
+- name: Commit if changed
+  run: |
+    git add surfaice/
+    git diff --staged --quiet || git commit -m "chore: update surfaice manifests"
+```

package/action.yml

@@ -0,0 +1,32 @@
+name: 'Surfaice UI Drift Check'
+description: 'Detect UI drift by comparing committed .surfaice.md files against a live app'
+author: 'surfaiceai'
+
+inputs:
+  base-url:
+    description: 'Base URL of the running app (e.g. https://preview.myapp.com)'
+    required: true
+  surfaice-dir:
+    description: 'Directory containing committed .surfaice.md files'
+    required: false
+    default: 'surfaice/'
+  fail-on-drift:
+    description: 'Fail the action if drift is detected'
+    required: false
+    default: 'true'
+  output-format:
+    description: 'Output format: "text" or "json"'
+    required: false
+    default: 'text'
+
+outputs:
+  drift-detected:
+    description: 'Whether UI drift was detected ("true" or "false")'
+  drift-summary:
+    description: 'Human-readable summary of drift (e.g. "2 added, 1 changed")'
+  diff-json:
+    description: 'JSON-encoded diff results array'
+
+runs:
+  using: 'node20'
+  main: 'dist/index.js'

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @surfaice/action — GitHub Action entry point
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * @surfaice/action — GitHub Action entry point
+ */
+import { readFileSync, readdirSync, existsSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import { parse } from '@surfaice/format';
+import { diff } from '@surfaice/differ';
+function getInput(name, defaultValue = '') {
+    const envName = `INPUT_${name.toUpperCase().replace(/-/g, '_')}`;
+    return process.env[envName] ?? defaultValue;
+}
+function setOutput(name, value) {
+    const outputFile = process.env.GITHUB_OUTPUT;
+    if (outputFile) {
+        appendFileSync(outputFile, `${name}=${value}\n`);
+    }
+    console.log(`::set-output name=${name}::${value}`);
+}
+async function run() {
+    const baseUrl = getInput('base-url');
+    const surfaiceDir = getInput('surfaice-dir', 'surfaice/');
+    const failOnDrift = getInput('fail-on-drift', 'true') !== 'false';
+    if (!baseUrl) {
+        console.error('::error::base-url input is required');
+        process.exit(1);
+    }
+    if (!existsSync(surfaiceDir)) {
+        console.error(`::error::Directory not found: ${surfaiceDir}`);
+        process.exit(1);
+    }
+    const files = readdirSync(surfaiceDir).filter((f) => f.endsWith('.surfaice.md'));
+    if (files.length === 0) {
+        console.log(`::warning::No .surfaice.md files found in ${surfaiceDir}`);
+        setOutput('drift-detected', 'false');
+        setOutput('drift-summary', 'No .surfaice.md files found');
+        return;
+    }
+    const diffs = [];
+    let failures = 0;
+    for (const file of files) {
+        const committed = readFileSync(join(surfaiceDir, file), 'utf-8');
+        const expected = parse(committed);
+        const route = expected.route;
+        let response;
+        try {
+            response = await fetch(new URL(route, baseUrl).toString(), {
+                headers: { 'Accept': 'text/surfaice' },
+            });
+        }
+        catch (err) {
+            console.error(`::error::Failed to fetch ${route}: ${String(err)}`);
+            failures++;
+            continue;
+        }
+        if (!response.ok) {
+            console.error(`::error::${route} returned ${response.status} ${response.statusText}`);
+            failures++;
+            continue;
+        }
+        const live = parse(await response.text());
+        const result = diff(expected, live);
+        diffs.push({ ...result, file });
+        if (result.status === 'match') {
+            console.log(`✅ ${route} — no drift`);
+        }
+        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++;
+        }
+    }
+    const driftDetected = diffs.some(d => d.status === 'drift') || failures > 0;
+    const summaries = diffs.filter(d => d.status === 'drift').map(d => `${d.route}: ${d.summary}`);
+    const driftSummary = summaries.length > 0 ? summaries.join('; ') : 'No drift detected';
+    setOutput('drift-detected', String(driftDetected));
+    setOutput('drift-summary', driftSummary);
+    setOutput('diff-json', JSON.stringify(diffs));
+    if (driftDetected && failOnDrift) {
+        console.error(`\n::error::UI drift detected! ${driftSummary}`);
+        process.exit(1);
+    }
+}
+run().catch((err) => {
+    console.error(`::error::${String(err)}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@surfaice/action",
+  "version": "0.0.1",
+  "description": "GitHub Action for detecting UI drift with Surfaice",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "action.yml",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/surfaiceai/surfaice",
+    "directory": "packages/action"
+  },
+  "dependencies": {
+    "@surfaice/differ": "0.0.1",
+    "@surfaice/format": "0.0.1"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0",
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  }
+}