@studiolxd/lxd-cli 0.1.0-next.0 → 0.1.0-next.1

package/README.md

@@ -53,6 +53,8 @@ lxd tracking   --report completion score success
 lxd validate                          # actionable pass/fail across all checks
 lxd handoff                           # write .agent/** specs + prompts + scaffold generated/
 #  → run YOUR agent against .agent/** to produce generated/
+#  → also writes .claude/commands/lxd-generate.md; in Claude Code run /project:lxd-generate
+#    (operational only — reads .agent/ as the source of truth; generic .agent/ stays agent-agnostic)
 lxd preview --mock-lms                # build + serve locally, with a mock LMS
 lxd export --target web --target scorm-1.2 --target scorm-2004
 ```

package/dist/cli/index.js

@@ -8,7 +8,7 @@ import { realpathSync } from "node:fs";
 // package.json
 var package_default = {
   name: "@studiolxd/lxd-cli",
-  version: "0.1.0-next.0",
+  version: "0.1.0-next.1",
   description: "CLI-first authoring tool for AI-native elearning packages (agent-orchestrated, framework- and export-target-agnostic).",
   type: "module",
   license: "UNLICENSED",
@@ -16,7 +16,7 @@ var package_default = {
     node: ">=20"
   },
   bin: {
-    lxd: "./dist/cli/index.js"
+    lxd: "dist/cli/index.js"
   },
   files: [
     "dist",
@@ -1542,13 +1542,13 @@ function register10(program) {
 }
 
 // src/cli/commands/handoff.ts
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 import { access as access4 } from "node:fs/promises";
 import { confirm, isCancel } from "@clack/prompts";
 
 // src/agent/handoff/producer.ts
-import { mkdir as mkdir4, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join7, dirname as dirname2 } from "node:path";
 
 // src/agent/handoff/scorm-skills.ts
 import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
@@ -1608,17 +1608,78 @@ async function writeScormSkillsSnapshot(agentDir, opts = {}) {
   return { ref: `${ref}@${version}` };
 }
 
-// src/core/project/assets.ts
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+// src/agent/handoff/claude-command.ts
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join5 } from "node:path";
+function renderClaudeCommand(opts) {
+  const lines = [
+    "# lxd-generate",
+    "",
+    "Operational instructions for implementing this LXD elearning package with Claude Code",
+    "(invoke as `/project:lxd-generate`). The `.agent/` directory is the SOURCE OF TRUTH \u2014",
+    "read it and implement to it; do not infer the learning design from anything else.",
+    "",
+    "## Read first",
+    "",
+    "1. Read `.agent/spec.md` (the package specification).",
+    "2. Read `.agent/instructions.md` (the agent instructions).",
+    "3. Read all relevant files under `.agent/prompts/` (one per experience, plus the package shell)."
+  ];
+  if (opts.scormSkills) {
+    lines.push("4. Read `.agent/scorm-skills/` (SCORM runtime guidance).");
+  }
+  lines.push(
+    "",
+    "Treat `.agent/` as the **source of truth** for the learning design.",
+    "",
+    "## Implement",
+    "",
+    "- Implement the package under `generated/`.",
+    "- Do not modify `.agent/` (the CLI regenerates it).",
+    "- Do not modify the package specification YAML files unless strictly necessary."
+  );
+  if (opts.scorm) {
+    lines.push(
+      "",
+      "## SCORM",
+      "",
+      "- Do not generate a custom SCORM runtime.",
+      "- Use `@studiolxd/scorm` as the runtime integration layer for all SCORM interactions.",
+      "- Follow the SCORM guidance emitted under `.agent/scorm-skills/`."
+    );
+  }
+  lines.push(
+    "",
+    "## Report",
+    "",
+    "When done, report the files you created or modified, then the next commands:",
+    "",
+    "- `lxd validate`",
+    "- `lxd preview`",
+    "- `lxd export`",
+    ""
+  );
+  return lines.join("\n");
+}
+async function writeClaudeCommand(packageDir, opts) {
+  const dir = join5(packageDir, ".claude", "commands");
+  await mkdir3(dir, { recursive: true });
+  const path = join5(dir, "lxd-generate.md");
+  await writeFile3(path, renderClaudeCommand(opts), "utf8");
+  return path;
+}
+
+// src/core/project/assets.ts
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join6 } from "node:path";
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var MANIFEST_PATH = [".elearning", "manifest.lock"];
 var RECOMMENDED_ASSETS = {
-  scormLibraryVersion: "^1.0.0",
+  scormLibraryVersion: "^2.0.0",
   scormSkillsSnapshot: { version: "main", ref: "github:studiolxd/scorm-skills" }
 };
 function manifestFile(dir) {
-  return join5(dir, ...MANIFEST_PATH);
+  return join6(dir, ...MANIFEST_PATH);
 }
 async function readManifest(dir) {
   try {
@@ -1628,8 +1689,8 @@ async function readManifest(dir) {
   }
 }
 async function writeManifest(dir, manifest) {
-  await mkdir3(join5(dir, ".elearning"), { recursive: true });
-  await writeFile3(manifestFile(dir), stringifyYaml2(manifest), "utf8");
+  await mkdir4(join6(dir, ".elearning"), { recursive: true });
+  await writeFile4(manifestFile(dir), stringifyYaml2(manifest), "utf8");
 }
 async function updateAssets(dir, update) {
   const manifest = await readManifest(dir);
@@ -1668,21 +1729,21 @@ function createHandoffProducer() {
     version: VERSION,
     async produce(input) {
       const out = input.outputDir;
-      await mkdir4(join6(out, "prompts"), { recursive: true });
+      await mkdir5(join7(out, "prompts"), { recursive: true });
       const spec = renderSpec(input);
-      const specPath = join6(out, "spec.md");
-      await writeFile4(specPath, spec, "utf8");
+      const specPath = join7(out, "spec.md");
+      await writeFile5(specPath, spec, "utf8");
       const prompts = [];
-      const shellPath = join6(out, "prompts", "package-shell.md");
-      await writeFile4(shellPath, renderShellPrompt(input), "utf8");
+      const shellPath = join7(out, "prompts", "package-shell.md");
+      await writeFile5(shellPath, renderShellPrompt(input), "utf8");
       prompts.push({ id: "package-shell", path: shellPath });
       for (const ref of input.package.experienceRefs) {
-        const p = join6(out, "prompts", `${ref}.md`);
-        await writeFile4(p, renderExperiencePrompt(ref, input), "utf8");
+        const p = join7(out, "prompts", `${ref}.md`);
+        await writeFile5(p, renderExperiencePrompt(ref, input), "utf8");
         prompts.push({ id: ref, path: p });
       }
       const instructions = renderInstructions(input);
-      await writeFile4(join6(out, "instructions.md"), instructions, "utf8");
+      await writeFile5(join7(out, "instructions.md"), instructions, "utf8");
       let scormSkillsSnapshotRef = input.scormSkills?.snapshotRef;
       if (input.targets.some((t) => t.startsWith("scorm"))) {
         const snap = await writeScormSkillsSnapshot(out, {
@@ -1691,13 +1752,19 @@ function createHandoffProducer() {
         });
         scormSkillsSnapshotRef = snap.ref;
       }
-      logger.debug({ outputDir: out, prompts: prompts.length }, "Agent handoff produced");
+      const scorm = isScormTargeted2(input.targets);
+      const claudeCommandPath = await writeClaudeCommand(dirname2(out), { scorm, scormSkills: scorm });
+      logger.debug(
+        { outputDir: out, prompts: prompts.length, claudeCommandPath },
+        "Agent handoff produced"
+      );
       return {
         spec,
         prompts,
         instructions,
         scormSkillsSnapshotRef,
-        producedBy: VERSION
+        producedBy: VERSION,
+        claudeCommandPath
       };
     }
   };
@@ -1815,13 +1882,13 @@ function renderInstructions(input) {
 }
 
 // src/adapters/framework/webcomponents/index.ts
-import { mkdir as mkdir5, writeFile as writeFile5, cp, access as access3 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { mkdir as mkdir6, writeFile as writeFile6, cp, access as access3 } from "node:fs/promises";
+import { join as join9 } from "node:path";
 
 // src/preview/server.ts
 import { createServer } from "node:http";
 import { readFile as readFile5, stat } from "node:fs/promises";
-import { join as join7, normalize, extname as extname2 } from "node:path";
+import { join as join8, normalize, extname as extname2 } from "node:path";
 
 // src/preview/mock-lms/index.ts
 function mockLmsBrowserScript() {
@@ -1877,13 +1944,13 @@ async function startPreviewServer(opts) {
           res.writeHead(200, { "content-type": MIME[".js"] }).end(mockLmsBrowserScript());
           return;
         }
-        const safe = normalize(join7(root, rel === "/" ? "index.html" : `.${rel}`));
+        const safe = normalize(join8(root, rel === "/" ? "index.html" : `.${rel}`));
         if (!safe.startsWith(root)) {
           res.writeHead(403).end("Forbidden");
           return;
         }
         const info = await stat(safe).catch(() => null);
-        const file = info?.isDirectory() ? join7(safe, "index.html") : safe;
+        const file = info?.isDirectory() ? join8(safe, "index.html") : safe;
         const isHtml = extname2(file) === ".html";
         if (opts.mockLms && isHtml) {
           const html = await readFile5(file, "utf8");
@@ -1930,21 +1997,21 @@ var webComponentsAdapter = {
   version: "0.1.0",
   optionsSchema: { type: "object", additionalProperties: true },
   async scaffold(input) {
-    await mkdir5(input.outputDir, { recursive: true });
+    await mkdir6(input.outputDir, { recursive: true });
     const files = [];
-    const configPath = join8(input.outputDir, "elearning.scaffold.json");
-    await writeFile5(
+    const configPath = join9(input.outputDir, "elearning.scaffold.json");
+    await writeFile6(
       configPath,
       JSON.stringify({ adapter: this.id, packageId: input.package.id }, null, 2),
       "utf8"
     );
     files.push(configPath);
-    const contractPath = join8(input.outputDir, "AGENT_IMPLEMENTATION.md");
-    await writeFile5(contractPath, IMPLEMENTATION_CONTRACT, "utf8");
+    const contractPath = join9(input.outputDir, "AGENT_IMPLEMENTATION.md");
+    await writeFile6(contractPath, IMPLEMENTATION_CONTRACT, "utf8");
     files.push(contractPath);
-    const generated = join8(input.outputDir, "generated");
-    await mkdir5(generated, { recursive: true });
-    const seed = join8(generated, "index.html");
+    const generated = join9(input.outputDir, "generated");
+    await mkdir6(generated, { recursive: true });
+    const seed = join9(generated, "index.html");
     const preserved = [];
     const overwritten = [];
     const seedExists = await exists(seed);
@@ -1952,7 +2019,7 @@ var webComponentsAdapter = {
       preserved.push(seed);
       logger.debug({ file: seed }, "Preserved existing generated/ file (use force to overwrite)");
     } else {
-      await writeFile5(seed, "<!doctype html><title>elearning package</title>", "utf8");
+      await writeFile6(seed, "<!doctype html><title>elearning package</title>", "utf8");
       files.push(seed);
       if (seedExists) {
         overwritten.push(seed);
@@ -1966,7 +2033,7 @@ var webComponentsAdapter = {
     return { files, implementationContract: IMPLEMENTATION_CONTRACT, preserved, overwritten };
   },
   async build(input) {
-    await mkdir5(input.outputDir, { recursive: true });
+    await mkdir6(input.outputDir, { recursive: true });
     const source = input.generatedDir;
     if (source && await exists(source)) {
       await cp(source, input.outputDir, { recursive: true });
@@ -2080,9 +2147,10 @@ function register11(program) {
       scormLibraryVersion: project.manifest?.scormLibraryVersion,
       frameworkContract: webComponentsAdapter.displayName,
       targets: opts.target,
-      outputDir: join9(dir, ".agent")
+      outputDir: join10(dir, ".agent")
     });
     console.log(`Handoff materials written to .agent/ (${materials.prompts.length} prompts).`);
+    console.log("Claude Code command written to .claude/commands/lxd-generate.md (run /project:lxd-generate).");
     const agnostic = checkHandoffAgnostic(`${materials.spec}
 ${materials.instructions}`);
     if (!agnostic.ok) {
@@ -2091,7 +2159,7 @@ ${materials.instructions}`);
       }
     }
     let force = Boolean(opts.force);
-    const seed = join9(dir, "generated", "index.html");
+    const seed = join10(dir, "generated", "index.html");
     if (!force && await exists2(seed)) {
       if (process.stdin.isTTY) {
         const answer = await confirm({
@@ -2126,15 +2194,15 @@ ${materials.instructions}`);
 }
 
 // src/cli/commands/preview.ts
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 function register12(program) {
   program.command("preview").description("Build the package and serve it locally").option("--mock-lms", "serve in mock LMS/SCORM mode (US2)").option("-p, --port <n>", "port", "0").action(async (opts, cmd) => {
     const dir = cwdOf(cmd);
     const project = await loadProjectLenient(dir);
     const built = await webComponentsAdapter.build({
       package: project.package,
-      outputDir: join10(dir, "build"),
-      generatedDir: join10(dir, "generated")
+      outputDir: join11(dir, "build"),
+      generatedDir: join11(dir, "generated")
     });
     const handle = await startPreviewServer({
       dir: built.outputDir,
@@ -2148,7 +2216,7 @@ function register12(program) {
 }
 
 // src/cli/commands/export.ts
-import { join as join13 } from "node:path";
+import { join as join14 } from "node:path";
 
 // src/core/authoring/export-builder.ts
 function buildExportConfig(targetIds) {
@@ -2181,7 +2249,7 @@ function createExportRegistry() {
 }
 
 // src/adapters/export/web/index.ts
-import { mkdir as mkdir6, cp as cp2, access as access5 } from "node:fs/promises";
+import { mkdir as mkdir7, cp as cp2, access as access5 } from "node:fs/promises";
 var webExportAdapter = {
   id: "web",
   displayName: "Web / static package",
@@ -2203,7 +2271,7 @@ var webExportAdapter = {
     ];
   },
   async export(input) {
-    await mkdir6(input.outputDir, { recursive: true });
+    await mkdir7(input.outputDir, { recursive: true });
     await cp2(input.builtDir, input.outputDir, { recursive: true });
     logger.debug({ outputDir: input.outputDir }, "web export complete");
     return { artifactPath: input.outputDir, target: "web", warnings: [] };
@@ -2211,8 +2279,8 @@ var webExportAdapter = {
 };
 
 // src/adapters/export/scorm12/index.ts
-import { mkdir as mkdir7, cp as cp3, writeFile as writeFile6, access as access6 } from "node:fs/promises";
-import { join as join11 } from "node:path";
+import { mkdir as mkdir8, cp as cp3, writeFile as writeFile7, access as access6 } from "node:fs/promises";
+import { join as join12 } from "node:path";
 
 // src/adapters/export/scorm-common.ts
 import archiver from "archiver";
@@ -2326,11 +2394,11 @@ var scorm12Adapter = {
     return results;
   },
   async export(input) {
-    await mkdir7(input.outputDir, { recursive: true });
+    await mkdir8(input.outputDir, { recursive: true });
     await cp3(input.builtDir, input.outputDir, { recursive: true });
-    await writeFile6(join11(input.outputDir, "imsmanifest.xml"), buildImsManifest12(input.package), "utf8");
-    await writeFile6(
-      join11(input.outputDir, "scorm-runtime.json"),
+    await writeFile7(join12(input.outputDir, "imsmanifest.xml"), buildImsManifest12(input.package), "utf8");
+    await writeFile7(
+      join12(input.outputDir, "scorm-runtime.json"),
       JSON.stringify(
         { library: "@studiolxd/scorm", version: input.assets.scormLibraryVersion ?? "unspecified", edition: "SCORM 1.2" },
         null,
@@ -2347,8 +2415,8 @@ var scorm12Adapter = {
 };
 
 // src/adapters/export/scorm2004/index.ts
-import { mkdir as mkdir8, cp as cp4, writeFile as writeFile7, access as access7 } from "node:fs/promises";
-import { join as join12 } from "node:path";
+import { mkdir as mkdir9, cp as cp4, writeFile as writeFile8, access as access7 } from "node:fs/promises";
+import { join as join13 } from "node:path";
 var scorm2004Adapter = {
   id: "scorm-2004",
   displayName: "SCORM 2004 (4th Edition)",
@@ -2380,11 +2448,11 @@ var scorm2004Adapter = {
     return results;
   },
   async export(input) {
-    await mkdir8(input.outputDir, { recursive: true });
+    await mkdir9(input.outputDir, { recursive: true });
     await cp4(input.builtDir, input.outputDir, { recursive: true });
-    await writeFile7(join12(input.outputDir, "imsmanifest.xml"), buildImsManifest2004(input.package), "utf8");
-    await writeFile7(
-      join12(input.outputDir, "scorm-runtime.json"),
+    await writeFile8(join13(input.outputDir, "imsmanifest.xml"), buildImsManifest2004(input.package), "utf8");
+    await writeFile8(
+      join13(input.outputDir, "scorm-runtime.json"),
       JSON.stringify(
         {
           library: "@studiolxd/scorm",
@@ -2426,8 +2494,8 @@ function register13(program) {
     }
     const built = await webComponentsAdapter.build({
       package: project.package,
-      outputDir: join13(dir, "build"),
-      generatedDir: join13(dir, "generated")
+      outputDir: join14(dir, "build"),
+      generatedDir: join14(dir, "generated")
     });
     for (const id of targets) {
       if (!registry.has(id)) {
@@ -2441,7 +2509,7 @@ function register13(program) {
         package: project.package,
         tracking: project.tracking,
         options: {},
-        outputDir: join13(dir, "dist", id),
+        outputDir: join14(dir, "dist", id),
         assets: {
           scormLibraryVersion: manifest.scormLibraryVersion,
           scormSkillsSnapshotRef: manifest.scormSkillsSnapshot?.ref
@@ -2474,7 +2542,7 @@ function register14(program) {
 }
 
 // src/cli/commands/create.ts
-import { join as join14, resolve as resolve5 } from "node:path";
+import { join as join15, resolve as resolve5 } from "node:path";
 import { rm } from "node:fs/promises";
 
 // src/cli/prompt.ts
@@ -2664,7 +2732,7 @@ async function runWizard(prompter, opts) {
       return result;
     }
     if (replacing) {
-      await rm(join14(targetDir, "experiences"), { recursive: true, force: true });
+      await rm(join15(targetDir, "experiences"), { recursive: true, force: true });
     }
     await saveProject(targetDir, assembleProject(answers, design));
     result.committed = true;
@@ -2687,7 +2755,7 @@ async function runWizard(prompter, opts) {
     if (await need(prompter.confirm({ message: "Generate agent handoff now?", initialValue: false }))) {
       await produceHandoff(await loadProjectLenient(result.dir), {
         targets: answers.exportTargets,
-        outputDir: join14(result.dir, ".agent")
+        outputDir: join15(result.dir, ".agent")
       });
       result.handoffGenerated = true;
       console.log("Handoff materials written to .agent/.");

package/docs/commands.md

@@ -19,7 +19,7 @@ revisitable.
 | `design -l <level> [-b <brief>] [--a11y <t...>] [--from <file>]` | 6 | Design direction (brief → full constraints). |
 | `evaluation -c <rule> [--assessed --pass-threshold <n>]` | 7 | Feedback + package completion/score rules. |
 | `tracking [--completion-rule] [--score-rule] [--report <fields...>] [--threshold <n>]` | 8 | Experience signals + package roll-up. |
-| `handoff [-t <targets...>] [-f]` | 9 | Generate `.agent/**` specs/prompts/instructions (full instructional context per experience: purpose, scenario, mechanic guidance + plugin enrichment, feedback, tracking; audience + package tone; source-of-truth instruction); scaffold `generated/`. |
+| `handoff [-t <targets...>] [-f]` | 9 | Generate `.agent/**` specs/prompts/instructions (full instructional context per experience: purpose, scenario, mechanic guidance + plugin enrichment, feedback, tracking; audience + package tone; source-of-truth instruction); scaffold `generated/`. Also writes a Claude Code convenience command at `.claude/commands/lxd-generate.md` (run `/project:lxd-generate`) — operational only; `.agent/` stays the source of truth. Generic `.agent/` materials are unchanged for non-Claude agents. |
 | *(your agent)* | 10 | Run YOUR AI coding agent against `.agent/**` to produce `generated/`. |
 | `preview [--mock-lms] [-p <port>]` | 11 | Build + serve locally; optional mock LMS/SCORM mode. |
 | `validate [--json]` | 12 | Run all validation checks on demand. For SCORM-targeted packages, **fails** if `generated/` hand-rolls a SCORM runtime instead of using `@studiolxd/scorm` (`no-custom-scorm-runtime`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiolxd/lxd-cli",
-  "version": "0.1.0-next.0",
+  "version": "0.1.0-next.1",
   "description": "CLI-first authoring tool for AI-native elearning packages (agent-orchestrated, framework- and export-target-agnostic).",
   "type": "module",
   "license": "UNLICENSED",
@@ -8,7 +8,7 @@
     "node": ">=20"
   },
   "bin": {
-    "lxd": "./dist/cli/index.js"
+    "lxd": "dist/cli/index.js"
   },
   "files": [
     "dist",