slicejs-cli 4.0.1 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -111,9 +111,41 @@ allowBuilds:
111
111
  | `slice get <component>` | Install components from the official registry |
112
112
  | `slice browse` | Browse available components |
113
113
  | `slice component create` | Create a local component |
114
+ | `slice skill add` | Install the Slice.js Claude Code skill into `.claude/skills/` |
114
115
  | `slice doctor` | Run project diagnostics |
115
116
  | `slice postinstall` | Configure npm scripts (alternative to postinstall) |
116
117
 
118
+ ## Claude Code skill (`slice skill`)
119
+
120
+ Installs the `slice-js-developer` skill — the guide Claude Code uses to build Slice.js
121
+ apps correctly — into your project by fetching it from the official docs repo
122
+ (`VKneider/slicejs_docs`), which is the single source of truth. A `manifest.json`
123
+ there pins the skill version, its framework-compatibility range, and the exact file
124
+ list, so the install never drifts.
125
+
126
+ | Command | Description |
127
+ |---------|-------------|
128
+ | `slice skill add` | Install the skill (prompts before overwriting an existing copy; `--force` skips the prompt) |
129
+ | `slice skill update` | Update the installed skill to the latest compatible version |
130
+ | `slice skill status` | Show the installed version vs. the latest available |
131
+
132
+ The skill is written to **`.claude/skills/slice-js-developer/`** at the **project
133
+ root** — inside Claude Code's standard skills path, not a loose folder next to `src/`:
134
+
135
+ ```
136
+ my-app/
137
+ ├── .claude/skills/slice-js-developer/ ← installed here
138
+ ├── api/
139
+ ├── src/ ← untouched
140
+ └── package.json
141
+ ```
142
+
143
+ > **Run `slice skill` commands from the project root.** All three subcommands
144
+ > (`add`, `update`, `status`) resolve the target from `INIT_CWD` / the current working
145
+ > directory, so running from a subfolder can place `.claude/` somewhere unexpected.
146
+ > The install path itself is configurable via the `installPath` field in the docs
147
+ > repo's `manifest.json`. After installing, reload Claude Code to pick up the skill.
148
+
117
149
  ## Postinstall Scripts
118
150
 
119
151
  When you install `slicejs-cli`, the `postinstall` script automatically configures `slice:*` npm scripts in your `package.json`:
package/client.js CHANGED
@@ -6,6 +6,7 @@ import createComponent from "./commands/createComponent/createComponent.js";
6
6
  import listComponents from "./commands/listComponents/listComponents.js";
7
7
  import deleteComponent from "./commands/deleteComponent/deleteComponent.js";
8
8
  import getComponent, { listComponents as listRemoteComponents, syncComponents } from "./commands/getComponent/getComponent.js";
9
+ import { addSkill, statusSkill, updateSkill } from "./commands/skill/skill.js";
9
10
  import startServer from "./commands/startServer/startServer.js";
10
11
  import runDiagnostics from "./commands/doctor/doctor.js";
11
12
  import versionChecker from "./commands/utils/VersionChecker.js";
@@ -498,6 +499,38 @@ componentCommand
498
499
  // REGISTRY COMMAND GROUP - For component registry operations
499
500
  const registryCommand = sliceClient.command("registry").alias("reg").description("Manage components from official Slice.js repository");
500
501
 
502
+ // SKILL COMMAND GROUP - Claude Code skill fetched from the docs repo
503
+ const skillCommand = sliceClient.command("skill").description("Manage the Slice.js Claude Code skill (fetched from the official docs repo)");
504
+
505
+ skillCommand
506
+ .command("add")
507
+ .alias("install")
508
+ .description("Install the slice-js-developer skill into .claude/skills/")
509
+ .option("-f, --force", "Overwrite an already-installed skill without prompting")
510
+ .action(async (options) => {
511
+ await runWithVersionCheck(async () => {
512
+ await addSkill({ force: options.force });
513
+ });
514
+ });
515
+
516
+ skillCommand
517
+ .command("update")
518
+ .description("Update the installed skill to the latest compatible version")
519
+ .action(async () => {
520
+ await runWithVersionCheck(async () => {
521
+ await updateSkill();
522
+ });
523
+ });
524
+
525
+ skillCommand
526
+ .command("status")
527
+ .description("Show installed vs latest skill version")
528
+ .action(async () => {
529
+ await runWithVersionCheck(async () => {
530
+ await statusSkill();
531
+ });
532
+ });
533
+
501
534
  // TYPES COMMAND GROUP - TypeScript declarations from static props
502
535
  const typesCommand = sliceClient.command("types").description("Generate TypeScript declarations from component static props");
503
536
 
@@ -706,14 +739,16 @@ Common Usage Examples:
706
739
  slice list - List all local components
707
740
  slice doctor - Run project diagnostics
708
741
  slice types generate - Generate TypeScript typings for slice.build
742
+ slice skill add - Install the Slice.js Claude Code skill
709
743
  slice postinstall - Configure npm scripts in package.json
710
744
 
711
745
  Command Categories:
712
746
  • init, dev, start - Project lifecycle (development only)
713
- • get, browse, sync, list - Quick shortcuts
747
+ • get, browse, sync, list - Quick shortcuts
714
748
  • component <cmd> - Local component management
715
749
  • registry <cmd> - Official repository operations
716
750
  • types generate - Type declarations from static props
751
+ • skill <cmd> - Claude Code skill (add / update / status)
717
752
  • version, doctor, setup - Maintenance commands
718
753
 
719
754
  Development Workflow:
@@ -0,0 +1,236 @@
1
+ // commands/skill/skill.js
2
+ //
3
+ // Installs the Slice.js Claude Code skill (slice-js-developer) into a project's
4
+ // .claude/skills/ folder by fetching it from the docs repo. The docs repo is the
5
+ // single source of truth; a manifest.json there lists the version, the framework
6
+ // compatibility range, and the exact file list to copy — so nothing drifts.
7
+
8
+ import fs from "fs-extra";
9
+ import path from "path";
10
+ import inquirer from "inquirer";
11
+ import ora from "ora";
12
+ import Print from "../Print.js";
13
+ import { getProjectRoot } from "../utils/PathHelper.js";
14
+ import { fetchWithRetry, runConcurrent } from "../getComponent/getComponent.js";
15
+
16
+ // Canonical home: VKneider/slicejs_docs → /skill. The MCP already sources docs
17
+ // from this same repo, keeping the skill co-located with what it distills.
18
+ // Override with SLICE_SKILL_REPO_BASE_URL (a fork, a branch, or a local server for testing).
19
+ const SKILL_REPO_BASE_URL =
20
+ process.env.SLICE_SKILL_REPO_BASE_URL ||
21
+ "https://raw.githubusercontent.com/VKneider/slicejs_docs/master/skill";
22
+ const MANIFEST_URL = `${SKILL_REPO_BASE_URL}/manifest.json`;
23
+
24
+ async function fetchManifest() {
25
+ const raw = await fetchWithRetry(MANIFEST_URL, 3, 500, false);
26
+ let manifest;
27
+ try {
28
+ manifest = JSON.parse(raw);
29
+ } catch {
30
+ throw new Error("skill manifest is not valid JSON");
31
+ }
32
+ if (!manifest.name || !manifest.version || !Array.isArray(manifest.files) || !manifest.installPath) {
33
+ throw new Error("skill manifest is missing required fields (name, version, installPath, files)");
34
+ }
35
+ // The manifest is fetched over the network and drives where files get written.
36
+ // Never let it escape the install directory: reject absolute paths and any ".."
37
+ // segment in installPath or in a file entry (path-traversal hardening).
38
+ const unsafe = (p) =>
39
+ typeof p !== "string" || p.length === 0 || path.isAbsolute(p) || p.split(/[\\/]+/).includes("..");
40
+ if (unsafe(manifest.installPath)) {
41
+ throw new Error(`unsafe installPath in manifest: "${manifest.installPath}"`);
42
+ }
43
+ const badFile = manifest.files.find(unsafe);
44
+ if (badFile !== undefined) {
45
+ throw new Error(`unsafe file path in manifest: "${badFile}"`);
46
+ }
47
+ return manifest;
48
+ }
49
+
50
+ // The skill's own VERSION file is the source of truth for what's installed.
51
+ function readLocalVersion(installDir) {
52
+ const versionPath = path.join(installDir, "VERSION");
53
+ if (!fs.pathExistsSync(versionPath)) return null;
54
+ const raw = fs.readFileSync(versionPath, "utf8");
55
+ const line = raw.split("\n").find((l) => l.trim().toLowerCase().startsWith("version:"));
56
+ return line ? line.slice(line.indexOf(":") + 1).trim() : null;
57
+ }
58
+
59
+ // First integer in a version-ish string ("4.0.1" / "^4.0.x" → 4).
60
+ function majorOf(value) {
61
+ const m = String(value || "").match(/(\d+)/);
62
+ return m ? parseInt(m[1], 10) : null;
63
+ }
64
+
65
+ // Best-effort read of the installed framework version (real installed wins over
66
+ // a declared range). Returns null when it can't be determined.
67
+ function detectFrameworkVersion(projectRoot) {
68
+ const installed = path.join(projectRoot, "node_modules", "slicejs-web-framework", "package.json");
69
+ if (fs.pathExistsSync(installed)) {
70
+ try {
71
+ return JSON.parse(fs.readFileSync(installed, "utf8")).version;
72
+ } catch {
73
+ /* fall through */
74
+ }
75
+ }
76
+ const projectPkg = path.join(projectRoot, "package.json");
77
+ if (fs.pathExistsSync(projectPkg)) {
78
+ try {
79
+ const pkg = JSON.parse(fs.readFileSync(projectPkg, "utf8"));
80
+ return (pkg.dependencies && pkg.dependencies["slicejs-web-framework"]) ||
81
+ (pkg.devDependencies && pkg.devDependencies["slicejs-web-framework"]) ||
82
+ null;
83
+ } catch {
84
+ /* fall through */
85
+ }
86
+ }
87
+ return null;
88
+ }
89
+
90
+ // Soft compatibility gate: warns on a major mismatch, never blocks.
91
+ function reportCompatibility(manifest, projectRoot) {
92
+ const fw = detectFrameworkVersion(projectRoot);
93
+ if (!fw) {
94
+ Print.info("Could not detect slicejs-web-framework in this project — skipping compatibility check.");
95
+ return;
96
+ }
97
+ const targetMajor = majorOf(manifest.targets);
98
+ const fwMajor = majorOf(fw);
99
+ if (targetMajor != null && fwMajor != null && targetMajor !== fwMajor) {
100
+ Print.warning(
101
+ `Skill v${manifest.version} targets ${manifest.targets}, but this project uses slicejs-web-framework@${fw}. ` +
102
+ `Installing anyway — verify the guidance matches your framework version.`
103
+ );
104
+ } else {
105
+ Print.info(`Compatible with slicejs-web-framework@${fw} (targets ${manifest.targets}).`);
106
+ }
107
+ }
108
+
109
+ async function downloadSkillFiles(manifest, installDir) {
110
+ const total = manifest.files.length;
111
+ let done = 0;
112
+ const failed = [];
113
+ const spinner = ora(`Downloading skill 0/${total}`).start();
114
+ const worker = async (file) => {
115
+ const url = `${SKILL_REPO_BASE_URL}/${manifest.name}/${file}`;
116
+ const dest = path.join(installDir, file);
117
+ try {
118
+ const content = await fetchWithRetry(url, 3, 500, false);
119
+ await fs.ensureDir(path.dirname(dest));
120
+ await fs.writeFile(dest, content, "utf8");
121
+ } catch {
122
+ failed.push(file);
123
+ } finally {
124
+ done += 1;
125
+ spinner.text = `Downloading skill ${done}/${total}`;
126
+ }
127
+ };
128
+ await runConcurrent(manifest.files, worker, 4);
129
+ spinner.stop();
130
+ return failed;
131
+ }
132
+
133
+ // Install (or reinstall) the skill. `force` skips the overwrite prompt.
134
+ async function addSkill(options = {}) {
135
+ const projectRoot = getProjectRoot(import.meta.url);
136
+
137
+ let manifest;
138
+ try {
139
+ manifest = await fetchManifest();
140
+ } catch (error) {
141
+ Print.error(`Could not load the skill manifest from the docs repository: ${error.message}`);
142
+ Print.info("Check your internet connection and try again.");
143
+ return false;
144
+ }
145
+
146
+ const installDir = path.join(projectRoot, manifest.installPath);
147
+ const localVersion = readLocalVersion(installDir);
148
+
149
+ if (await fs.pathExists(installDir) && !options.force) {
150
+ if (localVersion === manifest.version) {
151
+ Print.info(`Skill '${manifest.name}' v${manifest.version} is already installed and up to date.`);
152
+ Print.commandExample("Reinstall anyway", "slice skill add --force");
153
+ return true;
154
+ }
155
+ const { overwrite } = await inquirer.prompt([
156
+ {
157
+ type: "confirm",
158
+ name: "overwrite",
159
+ message: localVersion
160
+ ? `Skill '${manifest.name}' v${localVersion} is installed; replace it with v${manifest.version}?`
161
+ : `'${manifest.installPath}' already exists; overwrite it with skill v${manifest.version}?`,
162
+ default: true,
163
+ },
164
+ ]);
165
+ if (!overwrite) {
166
+ Print.info("Installation cancelled.");
167
+ return false;
168
+ }
169
+ }
170
+
171
+ reportCompatibility(manifest, projectRoot);
172
+
173
+ const failed = await downloadSkillFiles(manifest, installDir);
174
+ if (failed.length === manifest.files.length) {
175
+ Print.error("Failed to download the skill — no files were written.");
176
+ return false;
177
+ }
178
+ if (failed.length > 0) {
179
+ Print.warning(`Some files couldn't be downloaded: ${failed.join(", ")}`);
180
+ }
181
+
182
+ Print.success(`Skill '${manifest.name}' v${manifest.version} installed at ${manifest.installPath}/`);
183
+ Print.info("Reload Claude Code (or restart the session) to pick up the skill.");
184
+ return true;
185
+ }
186
+
187
+ // Update = install the latest, replacing an existing copy without prompting.
188
+ async function updateSkill(options = {}) {
189
+ const projectRoot = getProjectRoot(import.meta.url);
190
+ const installDir = (() => {
191
+ // installPath comes from the manifest; peek at the default so we can report
192
+ // the current version before fetching. Falls back gracefully if absent.
193
+ return path.join(projectRoot, ".claude", "skills", "slice-js-developer");
194
+ })();
195
+ const before = readLocalVersion(installDir);
196
+ if (before) Print.info(`Currently installed: v${before}`);
197
+ return addSkill({ ...options, force: true });
198
+ }
199
+
200
+ // Show installed vs latest, and whether an update is available.
201
+ async function statusSkill() {
202
+ const projectRoot = getProjectRoot(import.meta.url);
203
+
204
+ let manifest;
205
+ try {
206
+ manifest = await fetchManifest();
207
+ } catch (error) {
208
+ Print.error(`Could not load the skill manifest from the docs repository: ${error.message}`);
209
+ Print.info("Check your internet connection and try again.");
210
+ return false;
211
+ }
212
+
213
+ const installDir = path.join(projectRoot, manifest.installPath);
214
+ const localVersion = readLocalVersion(installDir);
215
+
216
+ Print.title("Slice.js Claude Code skill");
217
+ console.log(` name: ${manifest.name}`);
218
+ console.log(` latest: v${manifest.version} (targets ${manifest.targets})`);
219
+ console.log(` installed: ${localVersion ? "v" + localVersion : "not installed"}`);
220
+ console.log(` files: ${manifest.files.length}`);
221
+ console.log(` path: ${manifest.installPath}/`);
222
+ Print.newLine();
223
+
224
+ if (!localVersion) {
225
+ Print.commandExample("Install the skill", "slice skill add");
226
+ } else if (localVersion !== manifest.version) {
227
+ Print.info(`Update available: v${localVersion} → v${manifest.version}`);
228
+ Print.commandExample("Update", "slice skill update");
229
+ } else {
230
+ Print.success("Installed skill is up to date.");
231
+ }
232
+ return true;
233
+ }
234
+
235
+ export default addSkill;
236
+ export { addSkill, updateSkill, statusSkill };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "slicejs-cli",
3
- "version": "4.0.1",
3
+ "version": "4.1.0",
4
4
  "description": "Command client for developing web applications with Slice.js framework",
5
5
  "main": "client.js",
6
6
  "bin": {