@krapwoo/ds-viewer 0.4.0 → 0.4.1

package/README.md

@@ -355,6 +355,17 @@ Set `starterKit.root` in `ds-viewer.config.ts` if you moved the kit after `init
 (default `src/ds`); a config from before 0.4 with no `root` field still works — it's inferred from
 your first `components` glob.
 
+### Updating: known limits
+
+- **Updating needs the network.** If npm doesn't answer within 20 seconds, the update page shows
+  "Couldn’t prepare the update" and nothing changes. It doesn't fall back to npm's cache, because
+  the install that follows would need the network anyway.
+- **A console error while installing is expected.** While npm replaces the package, Metro briefly
+  reports that it can't resolve `@krapwoo/ds-viewer`. The update page keeps going, and the viewer
+  restarts on the new version.
+- **Windows hasn't been tested on a real machine yet.** Package-manager commands run through a
+  shell on Windows (needed for `npm.cmd`), and this is covered by unit tests only.
+
 ## What's included
 
 Tokens · Icons (45) · and generic components:

package/dist/cli/dev.js

@@ -14,7 +14,7 @@ import { readOwnVersion } from "./packageVersion.js";
 import { createUpdateEndpoint } from "./endpoint.js";
 import { buildUpdatePlan } from "./updatePlan.js";
 import { lastSummaryLine } from "./doctor.js";
-import { detectPackageManager, installUpgradeCommand } from "./packageManager.js";
+import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
 export class LocalInstallMissingError extends Error {
 }
 const IGNORED_WATCH_SEGMENTS = new Set(['.ds-viewer', 'node_modules', '.git']);
@@ -80,7 +80,10 @@ export async function refreshUpdateFile(config, ownVersion, options = {}) {
 // `/update/status` polls throughout (Critical finding, Fable correction pass: the synchronous
 // version blocked the entire event loop until the whole update finished).
 const execFileAsync = promisify(execFile);
-const defaultExecImpl = async (command, args, options) => (await execFileAsync(command, args, options)).stdout;
+const defaultExecImpl = async (command, args, options) => {
+    const run = platformCommand(command, args);
+    return (await execFileAsync(run.command, run.args, { ...options, shell: run.shell })).stdout;
+};
 function installedMainJs(projectRoot) {
     return path.join(projectRoot, 'node_modules', '@krapwoo', 'ds-viewer', 'dist', 'cli', 'main.js');
 }

package/dist/cli/packageManager.js

@@ -27,3 +27,14 @@ export function installUpgradeCommand(pm, pkg, version) {
         return { command: 'pnpm', args: ['add', '--save-dev', spec] };
     return { command: 'yarn', args: ['add', '--dev', spec] };
 }
+const WINDOWS_SHIMS = new Set(['npm', 'npx', 'pnpm', 'yarn']);
+/** On Windows, `npm`, `npx`, `pnpm` and `yarn` are `.cmd` shims, which Node refuses to run
+ *  without a shell (the CVE-2024-27980 fix). With a shell, Node joins the arguments with spaces,
+ *  so any argument containing a space or a shell metacharacter (a temp folder under
+ *  `C:\Users\Jane Doe\…`) is wrapped in double quotes. Real executables (`node`, `tar`, `git`)
+ *  and every other platform keep running without a shell. */
+export function platformCommand(command, args, platform = process.platform) {
+    if (platform !== 'win32' || !WINDOWS_SHIMS.has(command))
+        return { command, args, shell: false };
+    return { command, args: args.map((arg) => (/[\s"&|<>^()]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg)), shell: true };
+}

package/dist/cli/update.js

@@ -3,8 +3,8 @@ import { execFileSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildUpdatePlan } from "./updatePlan.js";
-import { detectPackageManager, installUpgradeCommand } from "./packageManager.js";
+import { buildUpdatePlan, isAlreadyUpToDate } from "./updatePlan.js";
+import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { lastSummaryLine } from "./doctor.js";
 function formatPlanHuman(plan) {
@@ -37,7 +37,7 @@ export async function runUpdate(config, options = {}) {
     const currentVersion = options.currentVersion ?? readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
     const plan = await (options.buildPlan ?? buildUpdatePlan)(config, currentVersion);
     if ('error' in plan)
-        return { output: plan.error, exitCode: 1 };
+        return { output: plan.error, exitCode: isAlreadyUpToDate(plan.error) ? 0 : 1 };
     const planText = formatPlanHuman(plan);
     if (options.dryRun)
         return { output: planText, exitCode: 0 };
@@ -55,7 +55,10 @@ export async function runUpdate(config, options = {}) {
         if (!proceed)
             return { output: 'Aborted: nothing was changed.', exitCode: 0 };
     }
-    const execImpl = options.execImpl ?? ((cmd, args, opts) => execFileSync(cmd, args, { ...opts, encoding: 'utf8' }));
+    const execImpl = options.execImpl ?? ((cmd, args, opts) => {
+        const run = platformCommand(cmd, args);
+        return execFileSync(run.command, run.args, { ...opts, encoding: 'utf8', shell: run.shell });
+    });
     const { command, args } = installUpgradeCommand(detectPackageManager(config.projectRoot), '@krapwoo/ds-viewer', plan.latest);
     try {
         execImpl(command, args, { cwd: config.projectRoot, encoding: 'utf8' });

package/dist/cli/updatePlan.js

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { detectPackageManager } from "./packageManager.js";
+import { detectPackageManager, platformCommand } from "./packageManager.js";
 import { listKitFileDiffs } from "./kitDiff.js";
 import { extractSummaryBullets, fetchWithTimeout } from "./updateCheck.js";
 import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
@@ -88,12 +88,21 @@ function defaultGitStatus(projectRoot, plannedPaths) {
         throw new GitStatusError(`git status failed: ${error.message}`);
     }
 }
+/** "Already on the latest version" is reported through the plan's `{ error }` channel, but it is not a
+ *  failure: `update` exits 0 for it, and the viewer shows it as up to date (`isAlreadyUpToDateError`). */
+export const ALREADY_UP_TO_DATE = 'Already on the latest version';
+export function isAlreadyUpToDate(error) {
+    return error.startsWith(ALREADY_UP_TO_DATE);
+}
 /** Design §5 "Update plan", steps 1-3, in full. Every external effect is injected (Global
  *  Constraints) — the real defaults are a real `npm view`/`npm pack`/`tar`/`node migrate` and a
  *  real `git status --porcelain`, exactly what Task 20's own Verdaccio spike already exercised. */
 export async function buildUpdatePlan(config, currentVersion, options = {}) {
     const execFileAsync = promisify(execFile);
-    const execImpl = options.execImpl ?? (async (cmd, args, opts) => (await execFileAsync(cmd, args, opts)).stdout);
+    const execImpl = options.execImpl ?? (async (cmd, args, opts) => {
+        const run = platformCommand(cmd, args);
+        return (await execFileAsync(run.command, run.args, { ...opts, shell: run.shell })).stdout;
+    });
     const fetchImpl = options.fetchImpl ?? fetch;
     const tmpDirImpl = options.tmpDirImpl ?? (() => mkdtempSync(path.join(tmpdir(), 'ds-viewer-update-')));
     const gitStatusImpl = options.gitStatusImpl ?? defaultGitStatus;
@@ -114,7 +123,7 @@ export async function buildUpdatePlan(config, currentVersion, options = {}) {
     // installed version ahead of the registry's own `npm view` result (e.g. a local prerelease) is
     // not something `update` should try to "downgrade" into.
     if (compareVersions(parseVersion(targetVersion), parseVersion(currentVersion)) <= 0) {
-        return { error: `Already on the latest version (${currentVersion}).` };
+        return { error: `${ALREADY_UP_TO_DATE} (${currentVersion}).` };
     }
     let migrateResult;
     // M4 (Minor, Fable correction pass): compared against the *downloaded target version's* own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",