@studiolxd/lxd-cli 0.1.0-next.0

package/docs/commands.md

@@ -0,0 +1,56 @@
+# Command reference
+
+All commands accept global options `--cwd <dir>` (project root) and `--log-format <pretty|json>`.
+User-facing output goes to stdout; structured logs (off by default) go to stderr — so
+`lxd validate --json` stdout is always pure JSON. Set `LOG_LEVEL=debug` to see internal logs.
+
+The 13-step authoring workflow (spec FR-005) maps to these commands. Order is guided but
+revisitable.
+
+| Command | Step | Purpose |
+|---------|------|---------|
+| `create [dir]` (alias `wizard`) | guided | Interactive, guided creation of a **new** package in one session (buffer → single commit → optional validate (default yes) / handoff (default no) → summary). Create-new only; confirm-to-replace on an existing package. |
+| `init [dir] --id <id>` | scaffold | Create a package project (separated artifacts + `manifest.lock`). |
+| `goal -g <text>` | 1 | Set/show the learning goal. |
+| `audience -d <desc> -m <min> --tone <t> --context <c>` | 2 | Audience, duration, context, tone. |
+| `structure -n <linear\|free\|guided> [--order <ids...>] [--sync]` | 3 | Navigation + experience order. |
+| `experience add\|list\|remove` | 4 | Manage experiences (`add --id --purpose --scenario --mechanic`). |
+| `mechanic list\|show --id <id>` | 5 | Browse official mechanics (consumed, not authored, in v1). |
+| `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/`. |
+| *(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`). |
+| `export --target <id...>` | 13 | Export to `web`, `scorm-1.2`, `scorm-2004`. |
+| `assets show\|update [--scorm-version] [--skills-version] [--skills-ref]` | — | Explicitly update external asset versions (never silent). |
+
+## Notes
+
+- **Design levels** (`-l`): `brief`, `tokens`, `patterns`, `design-system`, `full-constraints`.
+  Advanced levels are supplied via `--from <file>` (a YAML/JSON design-direction document); the CLI
+  validates it before saving. No GUI — CLI-first.
+- **Overwrite safety**: `handoff` scaffolds `generated/` non-destructively. Existing files are
+  preserved; pass `-f/--force` (or confirm interactively) to overwrite.
+- **Unknown export target** → clear error (export targets are adapters, not hardcoded).
+- **Exit codes**: non-zero when `validate` overall fails or an export target is unknown.
+
+## Mechanics
+
+Official mechanics live as declarative manifests in `src/mechanics/manifests/*.yml`. Adding a new
+official mechanic is additive (a manifest, optionally a code plugin in `src/mechanics/plugins/`) and
+requires no change to the core. v1 ships: `risk-detection`, `decision-simulation`,
+`diagnostic-challenge`, `branching-narrative`.
+
+## Release (manual)
+
+Published to npm as `@studiolxd/lxd-cli` under the **`next`** dist-tag (proprietary, `UNLICENSED`).
+Verify locally first, then publish manually — nothing auto-publishes:
+
+```bash
+npm run verify:pack                        # pack → clean-install → run installed lxd (--help/--version/mechanic list/init)
+npm publish --tag next --access public     # manual, after verify:pack passes
+```
+
+`prepack` rebuilds `dist/`; `prepublishOnly` gates on typecheck + lint + tests.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@studiolxd/lxd-cli",
+  "version": "0.1.0-next.0",
+  "description": "CLI-first authoring tool for AI-native elearning packages (agent-orchestrated, framework- and export-target-agnostic).",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "lxd": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "scripts": {
+    "build": "esbuild src/cli/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/cli/index.js --banner:js=\"#!/usr/bin/env node\" && node scripts/copy-assets.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test",
+    "verify:pack": "node scripts/verify-package.mjs",
+    "dev": "tsx src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "archiver": "^7.0.1",
+    "commander": "^12.1.0",
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.0.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^20.16.0",
+    "@typescript-eslint/eslint-plugin": "^8.13.0",
+    "@typescript-eslint/parser": "^8.13.0",
+    "@vitest/coverage-v8": "^2.1.4",
+    "esbuild": "^0.24.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.3.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}