@krapwoo/ds-viewer 0.4.0 → 0.4.2

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/init.js

@@ -2,7 +2,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFi
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { execFileSync } from 'node:child_process';
-import { preflight } from "./preflight.js";
+import { formatPreflightIssue, preflight } from "./preflight.js";
 import { detectComponentFolders, detectTokenFiles } from "./detect.js";
 import { ensureAgentsFileSection } from "./agentsFile.js";
 import { ensureGithubAction } from "./githubAction.js";
@@ -51,7 +51,7 @@ function detectIndent(raw) {
 export async function initExistingProject(projectRoot, options = {}) {
     const { errors, warnings } = preflight(projectRoot);
     if (errors.length > 0) {
-        return { messages: errors.map((issue) => `Missing ${issue.package}. Run: ${issue.installCommand}`), written: [], exitCode: 1 };
+        return { messages: errors.map(formatPreflightIssue), written: [], exitCode: 1 };
     }
     const componentFolders = detectComponentFolders(projectRoot, projectRoot);
     const tokenFiles = detectTokenFiles(projectRoot, projectRoot, (file) => readFileSync(file, 'utf8'));
@@ -218,7 +218,7 @@ export default defineConfig({
 export async function initNewProject(projectRoot, options = {}) {
     const { errors, warnings } = preflight(projectRoot);
     if (errors.length > 0) {
-        return { messages: errors.map((issue) => `Missing ${issue.package}. Run: ${issue.installCommand}`), written: [], exitCode: 1 };
+        return { messages: errors.map(formatPreflightIssue), written: [], exitCode: 1 };
     }
     const packageJson = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
     const installedPackages = { ...packageJson.dependencies, ...packageJson.devDependencies };

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/preflight.js

@@ -1,7 +1,11 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+/** One line per issue: the problem (or "Missing <package>.") and the command that fixes it. */
+export function formatPreflightIssue(issue) {
+    return `${issue.problem ?? `Missing ${issue.package}.`} Run: ${issue.installCommand}`;
+}
 const REQUIRED_PACKAGES = ['react-native-web', 'react-dom'];
-// @expo/metro-runtime is recommended, not required: Expo 57 web works without it (verified in the
+// @expo/metro-runtime is recommended, not required: Expo web works without it (verified in the
 // 0.1 spike and in native-preview's own node_modules, which has no @expo/metro-runtime installed
 // either) — design §1 "Host requirements" only warns when it is missing.
 const RECOMMENDED_PACKAGES = {
@@ -9,7 +13,9 @@ const RECOMMENDED_PACKAGES = {
     typescript: 'npm install --save-dev typescript',
 };
 const MIN_NODE = [20, 19, 0];
-const MIN_EXPO = [57, 0, 0];
+// Lowered from 57 in 0.4.2 (owner-approved): sync, doctor, the viewer and Update now were verified
+// end to end on a fresh Expo SDK 54 app and on Skiffr (Expo 54).
+const MIN_EXPO = [54, 0, 0];
 /** Accepts `x.y.z`, and a version with a missing minor/patch (e.g. `"57"`, `"^57"`) by defaulting
  *  the missing segments to 0 — a range specifier like `"^57"` must not be flagged as older than 57. */
 function parseVersion(version) {
@@ -46,7 +52,7 @@ export function preflight(projectRoot) {
         errors.push({ package: 'expo', installCommand: 'npx expo install expo' });
     }
     else if (!atLeast(expoVersion, MIN_EXPO)) {
-        errors.push({ package: 'expo', installCommand: 'Upgrade to Expo SDK 57 or later: npx expo install expo@^57' });
+        errors.push({ package: 'expo', problem: `Expo SDK 54 or later is required (found ${expoVersion}).`, installCommand: 'npx expo install expo@^54' });
     }
     for (const name of REQUIRED_PACKAGES) {
         if (!deps[name])

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.2",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",

package/starter-kit/components/Banner/Banner.tsx

@@ -173,6 +173,11 @@ export function Banner({
   );
 }
 
+/** `StyleSheet.absoluteFill`, spelled out: React Native 0.81's types don't allow spreading
+ *  `StyleSheet.absoluteFill` (and 0.86 removed `absoluteFillObject`), so this one form
+ *  type-checks on both. */
+const FILL = { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 } as const;
+
 const styles = StyleSheet.create({
   actionRow: {
     flexDirection: 'row',
@@ -235,7 +240,7 @@ const styles = StyleSheet.create({
   },
   // Translucent pressed overlay — sits above the banner bg so the tinted bg shows through.
   pressOverlay: {
-    ...StyleSheet.absoluteFill,
+    ...FILL,
     backgroundColor: DS_SEMANTIC.interaction.pressed,
     borderRadius: DS_RADIUS.medium,
   },

package/starter-kit/components/BottomSheet/BottomSheet.tsx

@@ -125,9 +125,14 @@ export function BottomSheet({ visible, onDismiss, header, children, footer, styl
   );
 }
 
+/** `StyleSheet.absoluteFill`, spelled out: React Native 0.81's types don't allow spreading
+ *  `StyleSheet.absoluteFill` (and 0.86 removed `absoluteFillObject`), so this one form
+ *  type-checks on both. */
+const FILL = { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 } as const;
+
 const styles = StyleSheet.create({
-  overlay: { ...StyleSheet.absoluteFill, justifyContent: 'flex-end' },
-  backdrop: { ...StyleSheet.absoluteFill, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  overlay: { ...FILL, justifyContent: 'flex-end' },
+  backdrop: { ...FILL, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
   sheet: {
     maxHeight: MAX_HEIGHT_PERCENT,
     backgroundColor: DS_SEMANTIC.surface.white,

package/starter-kit/components/Dialog/Dialog.tsx

@@ -63,14 +63,19 @@ export function Dialog({ visible, onDismiss, children, style }: DialogProps) {
   );
 }
 
+/** `StyleSheet.absoluteFill`, spelled out: React Native 0.81's types don't allow spreading
+ *  `StyleSheet.absoluteFill` (and 0.86 removed `absoluteFillObject`), so this one form
+ *  type-checks on both. */
+const FILL = { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 } as const;
+
 const styles = StyleSheet.create({
   overlay: {
-    ...StyleSheet.absoluteFill,
+    ...FILL,
     alignItems: 'center',
     justifyContent: 'center',
     padding: DS_SPACING[800],
   },
-  backdrop: { ...StyleSheet.absoluteFill, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  backdrop: { ...FILL, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
   card: {
     width: '100%',
     maxWidth: 400,