@amityco/social-plus-vise 1.0.0 → 1.1.0

package/dist/server.js

@@ -57,9 +57,6 @@ const tools = new Map([
     getSdkFactsTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
-// Pre-rebrand `install-skill` runs created skill dirs/files under this name. We
-// supersede (remove) them on install so a host doesn't keep serving stale
-// foundry/spf guidance alongside the current skill.
 const legacySkillName = "social-plus-foundry";
 const cliResult = await handleCli(process.argv.slice(2));
 if (cliResult === "exit") {
@@ -102,6 +99,10 @@ async function handleCli(args) {
         console.log(`${packageName} ${packageVersion}`);
         return "exit";
     }
+    if (command === "--help-internal") {
+        console.log(helpText() + internalCommandsSection());
+        return "exit";
+    }
     if (command === "--help" || command === "-h" || command === "help") {
         console.log(helpText(args[1]));
         return "exit";
@@ -253,7 +254,17 @@ async function handleCli(args) {
             if (!errorMessage) {
                 const errorFile = flagValue(args, "error-file");
                 if (errorFile) {
-                    errorMessage = await readFile(path.resolve(errorFile), "utf8");
+                    const resolved = path.resolve(errorFile);
+                    try {
+                        errorMessage = await readFile(resolved, "utf8");
+                    }
+                    catch (error) {
+                        const code = error?.code;
+                        const why = code === "ENOENT" ? "file not found" : code === "EISDIR" ? "path is a directory" : "could not be read";
+                        console.error(`Could not read --error-file (${why}): ${resolved}`);
+                        process.exitCode = 1;
+                        return "exit";
+                    }
                 }
                 else if (!process.stdin.isTTY) {
                     const { readFileSync } = await import("node:fs");
@@ -324,9 +335,6 @@ async function handleCli(args) {
                 dryRun: hasFlag(args, "dry-run"),
                 surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
             });
-            // Reflect sensor outcome in the exit code so `vise run-sensors` is usable as a CI gate.
-            // Previously it always exited 0, so a failed/timed-out build silently read as green.
-            // dry-run / passed / no-sensors stay 0; only real failures fail.
             const status = toolResultStatus(printed);
             if (status === "failed" || status === "timed-out") {
                 process.exitCode = 1;
@@ -547,6 +555,17 @@ async function handleCli(args) {
     process.exitCode = 1;
     return "exit";
 }
+function internalCommandsSection() {
+    return `
+
+Internal commands (not part of the public surface — see docs/TOOLS.md):
+  vise sdk-facts --platform <p> [--capability <c>]  Read bundled SDK surface facts. Projectless, read-only.
+  vise blocks <list|plan|add> ...                   Install and validate social.plus blocks in customer projects.
+  vise resolve --request "..."                      Resolve a request into the closest supported Vise outcome.
+  vise skill-path                                   Print the bundled skill source path and install targets.
+
+Run \`vise <command> --help\` for any of the above.`;
+}
 function helpText(command) {
     if (command === "inspect") {
         return `${packageName} inspect
@@ -648,7 +667,7 @@ Usage:
   vise experience sensors [repoPath] --surface apps/web --no-write
 
 Output:
-  compile writes sp-vise/experience-compiler.json by default. The artifact summarizes install guidance, navigation wiring, per-surface plan/init commands, UX expectations, optional Block Factory bridge candidates, design adaptation, and validation commands. It does not edit source code.
+  compile writes sp-vise/experience-compiler.json by default. The artifact summarizes install guidance, navigation wiring, per-surface plan/init commands, UX expectations, optional block bridge candidates, design adaptation, and validation commands. It does not edit source code.
 
   sensors writes sp-vise/experience-sensors.json by default. The artifact summarizes advisory technical, design, UX, accessibility, and business-alignment evidence without changing vise check exit codes or producing a calibrated score.`;
     }
@@ -711,7 +730,7 @@ Targets:
   cursor  Installs to <repoPath>/.cursor/skills/social-plus-vise
   vscode  Installs to <repoPath>/.github/skills/social-plus-vise
   copilot Installs to <repoPath>/.github/skills/social-plus-vise
-  cursor-rules Writes <repoPath>/.cursor/rules/social-plus-vise.mdc
+  cursor-rules Writes <repoPath>/.cursor/rules/social-plus-vise.mdc plus .cursor/rules/reference/*.md
   custom  Use --dest <skillsRoot or exact skill directory>`;
     }
     if (command === "print-skill" || command === "print_skill") {
@@ -776,7 +795,7 @@ Usage:
     if (command === "sdk-facts" || command === "sdk_facts") {
         return `${packageName} sdk-facts
 
-Read bundled SDK surface facts for social.plus Block Factory planning. Internal, projectless, and read-only.
+Read bundled social.plus SDK surface facts for block packaging. Projectless and read-only.
 Symbol facts prove existence; --include-models adds extraction-grounded field-level model schemas
 (modelSchemas, plus capability model entries gain a schema). Platforms without grounded field data
 report modelFacts.status=absent instead of fabricated fields.
@@ -791,7 +810,7 @@ Usage:
     if (command === "blocks") {
         return `${packageName} blocks
 
-Install and validate social.plus Block Factory blocks inside customer projects.
+Install and validate social.plus blocks inside customer projects.
 
 Usage:
   vise blocks list --registry <path> --format json
@@ -892,6 +911,27 @@ init-tokens Scaffold src/styles/social-plus-tokens.css in the customer's project
            concrete values. Idempotent (never overwrites); use --force to overwrite.
            After editing, run vise design extract --from-project to refresh the contract.`;
     }
+    if (command === "engagement") {
+        return `${packageName} engagement
+
+Record and inspect the engagement-scope artifact (sp-vise/engagement.json) — the
+contractual record of which broad-social outcomes are in scope for this project.
+
+Usage:
+  vise engagement init [repoPath] --tier <free|pro|partner> --customer-id <id> --scope <outcome,...>
+  vise engagement init [repoPath] --scope feed,communities --target-completion 2026-12-31 \\
+    --reviewer-name "Jane Doe" --reviewer-email jane@example.com --evidence-upload-consent
+  vise engagement show [repoPath]
+
+Flags (init):
+  --tier <free|pro|partner>   Engagement tier (validated).
+  --customer-id <id>          Customer identifier recorded in the artifact.
+  --scope <outcome,...>       In-scope broad-social outcomes (repeatable; comma-separated).
+  --target-completion <date>  Target completion date, YYYY-MM-DD.
+  --reviewer-name <name>      Human reviewer recorded on the engagement.
+  --reviewer-email <email>    Human reviewer contact.
+  --evidence-upload-consent   Record consent to upload evidence during review.`;
+    }
     return `${packageName}
 
 Skill-guided deterministic CLI for social.plus SDK integration assistance.
@@ -919,11 +959,11 @@ Usage:
   vise sync [repoPath]             Persist deterministic-pass evidence
   vise attest [repoPath] --rule ... Record a compliance attestation
   vise explain <ruleId>            Explain one compliance rule
+  vise engagement init [repoPath]  Record the engagement-scope artifact (see vise engagement --help)
+  vise engagement show [repoPath]  Show the recorded engagement scope
   vise status [repoPath]           Print compliance summary
   vise validate [repoPath]         Validate setup and common risks
   vise run-sensors [repoPath]      Run detected project sensors
-  vise sdk-facts --platform ...    Internal SDK surface facts for Block Factory
-  vise blocks ...                  Install and validate Block Factory blocks
   vise design extract <prototype>  Extract a design contract from an HTML/CSS prototype
   vise design check [repoPath]     Advisory (non-blocking) UI-vs-contract conformance report
   vise design preview [repoPath]   Write an HTML visual review of the contract + conformance
@@ -932,7 +972,7 @@ Usage:
   vise --version                   Show package version
 
 Compatibility aliases:
-  spf, social-plus-vise, foundry, social-plus-foundry, foundry-mcp
+  spf, social-plus-vise
 
 MCP config:
   {
@@ -953,7 +993,6 @@ async function printToolResult(tool, input) {
     console.log(text);
     return { result, text };
 }
-// Parse the `status` field from a tool's printed JSON payload (best-effort).
 function toolResultStatus(printed) {
     try {
         const payload = JSON.parse(printed.text);
@@ -984,11 +1023,6 @@ async function installSkill(args) {
         nextStep: "Restart or reload the host AI coding tool so it discovers the installed skill.",
     };
 }
-// Supersede a pre-rebrand skill install: a prior `install-skill` under the old
-// package name created a sibling `<skillsRoot>/social-plus-foundry/` directory. Left
-// in place, the host keeps offering stale spf/foundry guidance next to the current
-// skill. Remove it on install — but only when it actually looks like a skill dir
-// (contains SKILL.md) and is not the directory we're installing into.
 async function removeLegacySkillDir(destination) {
     const legacyDir = path.join(path.dirname(destination), legacySkillName);
     if (legacyDir === destination) {
@@ -1002,43 +1036,46 @@ async function removeLegacySkillDir(destination) {
 }
 async function installInstructionFile(target, args) {
     const force = hasFlag(args, "force");
-    const source = path.join(skillSourceDir(), "SKILL.md");
+    const skillDir = skillSourceDir();
+    const source = path.join(skillDir, "SKILL.md");
     const content = await readFile(source, "utf8");
-    const legacyRule = path.join(path.dirname(target.destination), `${legacySkillName}.mdc`);
+    const rulesDir = path.dirname(target.destination);
+    const legacyRule = path.join(rulesDir, `${legacySkillName}.mdc`);
     const supersededLegacy = [];
     if (legacyRule !== target.destination && (await fileExists(legacyRule))) {
         await rm(legacyRule, { force: true });
         supersededLegacy.push(legacyRule);
     }
+    const installedFiles = [];
+    let mdcUpToDate = false;
     if (await fileExists(target.destination)) {
         const existing = await readFile(target.destination, "utf8");
         if (existing === content) {
-            return {
-                status: "already-current",
-                skill: bundledSkillName,
-                host: target.host,
-                source,
-                destination: target.destination,
-                force,
-                installedFiles: [],
-                supersededLegacy,
-                nextStep: "Restart or reload the host AI coding tool so it discovers the updated project instructions.",
-            };
+            mdcUpToDate = true;
         }
-        if (!force) {
+        else if (!force) {
             throw new Error(`Instruction file already exists with different content: ${target.destination}. Re-run with --force to overwrite.`);
         }
     }
-    await mkdir(path.dirname(target.destination), { recursive: true });
-    await writeFile(target.destination, content, "utf8");
+    if (!mdcUpToDate) {
+        await mkdir(rulesDir, { recursive: true });
+        await writeFile(target.destination, content, "utf8");
+        installedFiles.push(target.destination);
+    }
+    const referenceSource = path.join(skillDir, "reference");
+    const hasReferenceDir = await stat(referenceSource).then((info) => info.isDirectory()).catch(() => false);
+    if (hasReferenceDir) {
+        const referenceDest = path.join(rulesDir, "reference");
+        installedFiles.push(...(await copyDirectory(referenceSource, referenceDest, force)));
+    }
     return {
-        status: "installed",
+        status: installedFiles.length > 0 ? "installed" : "already-current",
         skill: bundledSkillName,
         host: target.host,
         source,
         destination: target.destination,
         force,
-        installedFiles: [target.destination],
+        installedFiles,
         supersededLegacy,
         nextStep: "Restart or reload the host AI coding tool so it discovers the updated project instructions.",
     };