@amityco/social-plus-vise 0.12.4 → 0.12.5

package/README.md

@@ -251,6 +251,7 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 | `vise design check [path]` | Advisory, **non-blocking** report on how closely the UI code matches the contract (token coverage + on/off-contract color literals). Never fails a build and is **not** a `vise check` gate |
 | `vise design preview [path] [--reference <prototype>]` | Write a self-contained `sp-vise/design-preview.html`: the contract's tokens as visual swatches + the conformance report + the HTML reference embedded for side-by-side review. Vise renders the artifact; a human/VLM judges the visual match. Dependency-free — **not** an automated pixel diff |
 | `vise design reference [path] [--title <name>]` | Write a self-contained `sp-vise/design-reference.html`: human/VLM-readable design-system spec — token swatches, type samples, component demos, and a growth-layer summary. Pairs with `design-contract.json` (machine-readable). Use `--title` to name the design system (e.g. `--title Streamly`). Advisory — **not** an enforcement gate |
+| `vise design init-tokens [path] [--force]` | Scaffold `src/styles/social-plus-tokens.css` — the dedicated, customer-editable token file for social.plus features. **Greenfield:** neutral defaults (full `--sp-*` token set). **Brownfield:** seeded from your existing concrete tokens. Idempotent — never overwrites an existing file (use `--force` to override). After editing, run `vise design extract --from-project` to refresh the contract. `design_init_tokens` |
 
 The extracted contract is **advisory input for generation**, not an enforcement gate: a token-poor prototype yields a weaker — never wrong — contract, and absence of a prototype simply means no contract (the existing `*.design.reuse-detected-tokens` rules still cover reuse of a host project's own design system).
 

package/dist/server.js

@@ -7,7 +7,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, initCompliance, initComplianceTool, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
-import { designCheckTool, designExtractTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
+import { designCheckTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { planHarnessTool } from "./tools/harness.js";
 import { planIntegrationTool } from "./tools/integration.js";
@@ -38,6 +38,7 @@ const tools = new Map([
     designCheckTool,
     designPreviewTool,
     designReferenceTool,
+    designInitTokensTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
 const cliResult = await handleCli(process.argv.slice(2));
@@ -305,7 +306,15 @@ async function handleCli(args) {
                 });
                 return "exit";
             }
-            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "preview", or "reference".`);
+            if (sub === "init-tokens") {
+                assertOnlyKnownFlags(subArgs, ["force"], "design init-tokens");
+                await printToolResult(designInitTokensTool, {
+                    repoPath: positionalRepoPath(subArgs),
+                    force: hasFlag(subArgs, "force"),
+                });
+                return "exit";
+            }
+            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "preview", "reference", or "init-tokens".`);
             process.exitCode = 1;
             return "exit";
         }
@@ -515,6 +524,7 @@ Usage:
   vise design check [repoPath]
   vise design preview [repoPath] [--reference <prototypePath>]
   vise design reference [repoPath] [--title "Streamly"] [--no-write]
+  vise design init-tokens [repoPath] [--force]
 
 extract    Build a graded design contract and write it to sp-vise/design-contract.json.
            Declared CSS custom properties become exact tokens; repeated literal values
@@ -535,7 +545,12 @@ preview    Write a self-contained sp-vise/design-preview.html: the contract's to
 reference  Write a self-contained sp-vise/design-reference.html: human/VLM-readable
            design-system spec (token swatches, type samples, component demos, growth-layer
            summary). Pairs with the machine-readable design-contract.json. Use --title to
-           set the design system name. Advisory — not an enforcement gate.`;
+           set the design system name. Advisory — not an enforcement gate.
+init-tokens Scaffold src/styles/social-plus-tokens.css in the customer's project —
+           the dedicated editable token file for social.plus features. Greenfield:
+           neutral defaults. Brownfield (existing tokens found): seeded from their
+           concrete values. Idempotent (never overwrites); use --force to overwrite.
+           After editing, run vise design extract --from-project to refresh the contract.`;
     }
     return `${packageName}
 

package/dist/tools/design.js

@@ -157,7 +157,16 @@ export async function extractDesignContractFromProject(repoPath) {
         }
     }
     inputs.sort();
-    return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, file_count: inputs.length }, moduleTokens);
+    // Hash each source file so design check can detect staleness without re-extracting.
+    const input_digests = {};
+    for (const rel of inputs) {
+        try {
+            const content = await readFile(path.join(root, rel), "utf8");
+            input_digests[rel] = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+        }
+        catch { /* file read already succeeded above; defensive only */ }
+    }
+    return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, input_digests, file_count: inputs.length }, moduleTokens);
 }
 export async function writeDesignContract(repoPath, contract) {
     const sidecarDir = path.join(path.resolve(repoPath), "sp-vise");
@@ -381,6 +390,215 @@ function safeCss(value) {
     return value.replace(/[<>"]/g, "").slice(0, 200);
 }
 // ---------------------------------------------------------------------------
+// Social-plus token scaffold (vise design init-tokens)
+// ---------------------------------------------------------------------------
+//
+// Creates a dedicated `src/styles/social-plus-tokens.css` in the customer's
+// project — the single editable source for social.plus feature styling.
+// The contract always points at this file; customers edit it freely without
+// needing an AI agent. Design check detects changes and prompts re-extract.
+//
+// Two cases:
+//   Greenfield (no existing design system): scaffold Option-B neutral defaults.
+//   Brownfield (existing tokens found):     seed from their concrete values.
+//   Already exists: leave it untouched (idempotent — never clobbers edits).
+/** Relative path within the customer's project where sp tokens live. */
+export const SP_TOKENS_PATH = "src/styles/social-plus-tokens.css";
+/** Option-B neutral default — a clean, adaptive light-mode system using system
+ *  fonts. All token names use `--sp-` prefix to avoid collision with the
+ *  customer's own design system. Will be replaced with the official social.plus
+ *  palette (Option A) once that palette is finalised. */
+export const NEUTRAL_SP_TOKENS_DEFAULT = `/* social-plus-tokens.css — social.plus feature design system.
+ * This file controls the look of all social.plus features in your app.
+ * Edit freely. Run: vise design extract --from-project . to refresh the contract.
+ * NOTE: design check scans the whole project; the main-app palette appearing as
+ *       "off-contract" is expected and advisory only — not a failure. */
+:root {
+  /* ── Brand / interactive ───────────────────────────────── */
+  --sp-color-brand:           #1054DE;
+  --sp-color-brand-hover:     #0D47C5;
+  --sp-color-brand-subtle:    #EEF3FF;
+  --sp-color-brand-text:      #FFFFFF;
+
+  /* ── Backgrounds ───────────────────────────────────────── */
+  --sp-color-bg:              #FFFFFF;
+  --sp-color-surface:         #F8F9FA;
+  --sp-color-surface-raised:  #FFFFFF;
+  --sp-color-surface-hover:   #F0F2F4;
+  --sp-color-overlay:         rgba(0, 0, 0, 0.5);
+
+  /* ── Text ──────────────────────────────────────────────── */
+  --sp-color-text:            #0D1017;
+  --sp-color-text-muted:      #5C6370;
+  --sp-color-text-faint:      #9AA0AD;
+  --sp-color-text-disabled:   #C1C7CE;
+  --sp-color-text-on-brand:   #FFFFFF;
+
+  /* ── Semantic ──────────────────────────────────────────── */
+  --sp-color-success:         #1FAF64;
+  --sp-color-warning:         #F59E0B;
+  --sp-color-error:           #EF4444;
+  --sp-color-info:            #3B82F6;
+
+  /* ── Border ────────────────────────────────────────────── */
+  --sp-color-border:          #E5E7EB;
+  --sp-color-border-strong:   #D1D5DB;
+
+  /* ── Typography ────────────────────────────────────────── */
+  --sp-font-body:    system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+  --sp-font-display: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+  --sp-fs-xs:   12px;
+  --sp-fs-sm:   14px;
+  --sp-fs-md:   16px;
+  --sp-fs-lg:   20px;
+  --sp-fs-xl:   24px;
+  --sp-fs-2xl:  32px;
+  --sp-fw-regular: 400;
+  --sp-fw-medium:  500;
+  --sp-fw-bold:    700;
+  --sp-lh-tight:   1.2;
+  --sp-lh-normal:  1.5;
+  --sp-lh-relaxed: 1.7;
+  --sp-ls-tight:  -0.01em;
+  --sp-ls-wide:    0.04em;
+
+  /* ── Spacing ───────────────────────────────────────────── */
+  --sp-space-1:   4px;
+  --sp-space-2:   8px;
+  --sp-space-3:   12px;
+  --sp-space-4:   16px;
+  --sp-space-5:   24px;
+  --sp-space-6:   32px;
+  --sp-space-8:   48px;
+  --sp-space-10:  64px;
+
+  /* ── Radius ────────────────────────────────────────────── */
+  --sp-radius-sm:   6px;
+  --sp-radius-md:   10px;
+  --sp-radius-lg:   16px;
+  --sp-radius-xl:   24px;
+  --sp-radius-pill: 999px;
+
+  /* ── Border width ──────────────────────────────────────── */
+  --sp-border-width-thin:  1px;
+  --sp-border-width-base:  2px;
+  --sp-border-width-thick: 4px;
+
+  /* ── Elevation ─────────────────────────────────────────── */
+  --sp-shadow-1: 0 1px 3px rgba(0, 0, 0, 0.08);
+  --sp-shadow-2: 0 4px 16px rgba(0, 0, 0, 0.10);
+  --sp-shadow-3: 0 16px 40px rgba(0, 0, 0, 0.14);
+
+  /* ── Opacity ───────────────────────────────────────────── */
+  --sp-opacity-disabled: 0.4;
+  --sp-opacity-muted:    0.7;
+
+  /* ── Motion ────────────────────────────────────────────── */
+  --sp-duration-fast:  120ms;
+  --sp-duration-base:  200ms;
+  --sp-duration-slow:  400ms;
+  --sp-ease-standard:  cubic-bezier(0.4, 0, 0.2, 1);
+  --sp-ease-emphasized:cubic-bezier(0.2, 0, 0, 1);
+
+  /* ── Sizing ────────────────────────────────────────────── */
+  --sp-size-icon-sm: 16px;
+  --sp-size-icon-md: 24px;
+  --sp-size-icon-lg: 32px;
+  --sp-control-height-sm: 32px;
+  --sp-control-height-md: 40px;
+  --sp-control-height-lg: 48px;
+
+  /* ── Z-index ───────────────────────────────────────────── */
+  --sp-z-nav:      10;
+  --sp-z-dropdown: 100;
+  --sp-z-modal:    1000;
+  --sp-z-toast:    2000;
+
+  /* ── Breakpoints ───────────────────────────────────────── */
+  --sp-bp-sm: 640px;
+  --sp-bp-md: 768px;
+  --sp-bp-lg: 1024px;
+  --sp-bp-xl: 1280px;
+}
+`;
+export const designInitTokensTool = {
+    name: "design_init_tokens",
+    description: "Scaffold src/styles/social-plus-tokens.css in the customer's project — the dedicated, customer-editable token file for social.plus features. Greenfield: neutral defaults. Brownfield (existing tokens found): seed from their concrete values. Idempotent: never overwrites an existing file.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string", description: "Project root. Defaults to the current directory." },
+            force: { type: "boolean", description: "Overwrite existing social-plus-tokens.css (default false — never clobbers)." },
+        },
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = optionalStringField(args, "repoPath") ?? ".";
+        const force = args.force === true;
+        return textResult(await initSpTokens(repoPath, force));
+    },
+};
+export async function initSpTokens(repoPath, force = false) {
+    const root = path.resolve(repoPath);
+    const target = path.join(root, SP_TOKENS_PATH);
+    // Idempotent: don't overwrite unless forced.
+    try {
+        await stat(target);
+        if (!force) {
+            return {
+                status: "exists",
+                file: target,
+                message: `${SP_TOKENS_PATH} already exists — skipping. Use --force to overwrite.`,
+            };
+        }
+    }
+    catch { /* file doesn't exist — proceed to scaffold */ }
+    // Try brownfield seeding: extract concrete token values from the existing project.
+    const existingContract = await extractDesignContractFromProject(root);
+    const hasBrownfieldTokens = existingContract.tokens.length > 0;
+    let css;
+    let seededFrom;
+    if (hasBrownfieldTokens) {
+        // Seed from their existing concrete values, namespaced as --sp-*.
+        const lines = [
+            `/* social-plus-tokens.css — social.plus feature design system.`,
+            ` * Seeded from your existing design tokens on ${new Date().toISOString().slice(0, 10)}.`,
+            ` * Edit freely to customize social.plus features independently from your main app.`,
+            ` * Run: vise design extract --from-project . to refresh the contract. */`,
+            `:root {`,
+        ];
+        const categories = [...new Set(existingContract.tokens.map((t) => t.category))];
+        for (const cat of categories) {
+            const tokensInCat = existingContract.tokens.filter((t) => t.category === cat && t.name);
+            if (tokensInCat.length === 0)
+                continue;
+            lines.push(``, `  /* ── ${cat} ──────────────────────────────────────────── */`);
+            for (const t of tokensInCat) {
+                const spName = `--sp-${t.name.replace(/^--/, "")}`;
+                lines.push(`  ${spName}: ${t.value};   /* seeded from ${t.name} */`);
+            }
+        }
+        lines.push(`}`);
+        css = lines.join("\n") + "\n";
+        seededFrom = existingContract.source.inputs;
+    }
+    else {
+        // Greenfield: neutral Option-B defaults.
+        css = NEUTRAL_SP_TOKENS_DEFAULT;
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, css, "utf8");
+    return {
+        status: hasBrownfieldTokens ? "seeded" : "scaffolded",
+        file: target,
+        ...(seededFrom ? { seeded_from: seededFrom } : {}),
+        message: hasBrownfieldTokens
+            ? `Seeded ${SP_TOKENS_PATH} from your existing design tokens. Edit it to customize social.plus features, then run vise design extract --from-project .`
+            : `Scaffolded ${SP_TOKENS_PATH} with neutral defaults. Fill in your colors, then run vise design extract --from-project .`,
+    };
+}
+// ---------------------------------------------------------------------------
 // Design-system reference document (human/VLM-readable, advisory)
 // ---------------------------------------------------------------------------
 //
@@ -927,6 +1145,9 @@ export async function runDesignCheck(repoPath) {
             note: ADVISORY_NOTE,
         };
     }
+    // Freshness check: compare source file content hashes to those recorded at extract time.
+    // Advisory only — never blocks, just surfaces a nudge to re-extract.
+    const staleContract = await checkContractFreshness(repoRoot, contract);
     const files = (await collectFiles(repoRoot, MAX_SCAN_FILES)).filter((file) => SCAN_EXTS.has(path.extname(file).toLowerCase()));
     if (files.length === 0) {
         return { status: "no-sources", message: "No UI source files found to check against the contract.", contract: contractSummary(contract), note: ADVISORY_NOTE };
@@ -1018,9 +1239,35 @@ export async function runDesignCheck(repoPath) {
             count: undefinedRefs.length,
             sample: undefinedRefs.slice(0, OFF_CONTRACT_SAMPLE),
         },
+        ...(staleContract ? { staleContract } : {}),
         note: ADVISORY_NOTE,
     };
 }
+/** Compare source.inputs file content against hashes recorded at extract time.
+ *  Returns null if the contract is fresh or has no recorded digests. */
+async function checkContractFreshness(repoRoot, contract) {
+    const recorded = contract.source?.input_digests;
+    if (!recorded || Object.keys(recorded).length === 0)
+        return undefined;
+    const changed = [];
+    for (const [rel, storedDigest] of Object.entries(recorded)) {
+        try {
+            const content = await readFile(path.join(repoRoot, rel), "utf8");
+            const currentDigest = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+            if (currentDigest !== storedDigest)
+                changed.push(rel);
+        }
+        catch {
+            changed.push(rel); // file deleted or unreadable — also stale
+        }
+    }
+    if (changed.length === 0)
+        return undefined;
+    return {
+        changedFiles: changed,
+        hint: `Run \`vise design extract --from-project\` to refresh the contract against the updated file(s).`,
+    };
+}
 function dedupeByToken(refs) {
     const seen = new Set();
     const out = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",