plotlink-ows 1.0.32 → 1.2.94

package/bin/plotlink-ows.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 // PlotLink OWS — CLI Wizard
-// Zero external dependencies — Node builtins only
+// Zero external dependencies — Node builtins + one in-package helper only.
 
 const fs = require("fs");
 const path = require("path");
 const readline = require("readline");
 const { execSync, spawn } = require("child_process");
 const crypto = require("crypto");
+const { planStartup, shouldAutoOpen } = require("./startup-plan.cjs");
 
 const CONFIG_DIR = path.join(require("os").homedir(), ".plotlink-ows");
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
@@ -203,6 +204,19 @@ async function cmdInit() {
   process.exit(0);
 }
 
+// Are the runtime dependencies resolvable? Resolve a known runtime dep rather
+// than probing `PROJECT_DIR/node_modules` directly — under a global (`-g`)
+// install the package's deps are hoisted to a sibling `node_modules`, so that
+// directory may not exist even though the deps resolve fine up the tree.
+function runtimeDepsInstalled() {
+  try {
+    require.resolve("tsx", { paths: [PROJECT_DIR] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function cmdStart() {
   const config = readConfig();
   if (!config) {
@@ -211,28 +225,51 @@ function cmdStart() {
     process.exit(1);
   }
 
-  // Ensure deps installed
-  if (!fs.existsSync(path.join(PROJECT_DIR, "node_modules"))) {
-    log("Installing dependencies...");
+  // Runtime/build-time boundary (#470, EPIC #465): an installed package ships
+  // prebuilt assets and only runtime deps, so the start path must NOT run a web
+  // build or `npm install` here — that would fetch the build toolchain from the
+  // network (an unexpected rebuild on a user's machine). Only a source checkout
+  // (detected by `src/`, which is never in the published tarball) may build.
+  // Missing assets in an installed package mean a corrupted install.
+  const plan = planStartup({
+    isSourceCheckout: fs.existsSync(path.join(PROJECT_DIR, "src")),
+    depsInstalled: runtimeDepsInstalled(),
+    distBuilt: fs.existsSync(path.join(PROJECT_DIR, "app", "web", "dist", "index.html")),
+  });
+
+  if (plan.error) {
+    const what = plan.error === "deps"
+      ? "Runtime dependencies are missing (node_modules)"
+      : "Prebuilt web assets are missing (app/web/dist)";
+    error(`${what} — this looks like a corrupted install.`);
+    log("Reinstall and try again:");
+    log("  \x1b[1mnpx plotlink-ows@latest\x1b[0m        (or)");
+    log("  \x1b[1mnpm install -g plotlink-ows@latest\x1b[0m");
+    process.exit(1);
+  }
+  if (plan.install) {
+    log("Installing dependencies (source checkout)...");
     execSync("npm install", { cwd: PROJECT_DIR, stdio: "inherit" });
   }
-
-  // Ensure frontend is built
-  const distDir = path.join(PROJECT_DIR, "app", "web", "dist");
-  if (!fs.existsSync(distDir)) {
-    log("Building frontend...");
+  if (plan.build) {
+    log("Building frontend (source checkout)...");
     execSync("npx vite build --config app/vite.config.ts", { cwd: PROJECT_DIR, stdio: "inherit" });
   }
 
   const port = config.port || 7777;
 
-  // Auto-open browser after a short delay
-  setTimeout(() => {
-    try {
-      const openCmd = process.platform === "darwin" ? "open" : "xdg-open";
-      execSync(`${openCmd} http://localhost:${port}`, { stdio: "ignore" });
-    } catch { /* ignore */ }
-  }, 2000);
+  // Auto-open browser after a short delay. Skipped for non-interactive runs
+  // (the release start smoke / preflight set PLOTLINK_OWS_NO_OPEN=1) so a publish
+  // check never pops a browser tab on the operator machine (#481). Normal
+  // `npx plotlink-ows` startup is unaffected.
+  if (shouldAutoOpen(process.env)) {
+    setTimeout(() => {
+      try {
+        const openCmd = process.platform === "darwin" ? "open" : "xdg-open";
+        execSync(`${openCmd} http://localhost:${port}`, { stdio: "ignore" });
+      } catch { /* ignore */ }
+    }, 2000);
+  }
 
   // Run server in foreground with visible logs
   const server = spawn("npx", ["tsx", "app/server.ts"], {

package/bin/startup-plan.cjs

@@ -0,0 +1,58 @@
+// Runtime/build-time boundary planner for the PlotLink OWS CLI (#470, EPIC #465).
+//
+// The published `plotlink-ows` package ships PREBUILT runtime assets
+// (`app/web/dist`) and installs only runtime `dependencies`. All build tooling
+// (vite, tailwind, react, …) lives in `devDependencies` (see #469) and is
+// therefore ABSENT from an installed package. Consequence: the `start` path must
+// NEVER run a web build or `npm install` on a user's machine — doing so would
+// fetch the build toolchain from the network (an unexpected rebuild). Missing
+// prebuilt assets in an installed package mean a CORRUPTED install, which we
+// surface loudly instead of silently trying to rebuild.
+//
+// A *source checkout* (the repo) is the only place a (re)build is allowed. It is
+// detected by the presence of `src/` (the Next.js web app), which is NOT part of
+// the published `files` allowlist and so never exists in an installed package.
+//
+// This module is intentionally PURE (no fs/process access) so the boundary
+// policy is unit-tested in isolation; `bin/plotlink-ows.js` probes the
+// environment and feeds the facts in.
+
+/**
+ * Decide what the `start` command must do before launching the server.
+ *
+ * @param {object} env
+ * @param {boolean} env.isSourceCheckout  running from the repo (has `src/`)
+ * @param {boolean} env.depsInstalled     runtime deps resolvable
+ * @param {boolean} env.distBuilt         prebuilt web UI present (app/web/dist/index.html)
+ * @returns {{ install: boolean, build: boolean, error: null | "deps" | "dist" }}
+ *   install/build are only ever `true` in a source checkout (dev convenience).
+ *   `error` is a fatal broken-install condition for an installed package.
+ */
+function planStartup({ isSourceCheckout, depsInstalled, distBuilt }) {
+  if (isSourceCheckout) {
+    // Dev convenience: bring a fresh checkout up without manual build steps.
+    return { install: !depsInstalled, build: !distBuilt, error: null };
+  }
+  // Installed package: never pull build tooling. Missing assets ⇒ broken install.
+  if (!depsInstalled) return { install: false, build: false, error: "deps" };
+  if (!distBuilt) return { install: false, build: false, error: "dist" };
+  return { install: false, build: false, error: null };
+}
+
+/**
+ * Decide whether `start` should auto-open the local app in a browser (#481).
+ *
+ * Normal `npx plotlink-ows` startup auto-opens for convenience. Non-interactive
+ * release checks (the packed start smoke / `npm run preflight`) set
+ * `PLOTLINK_OWS_NO_OPEN=1` so they never pop a browser tab on the operator
+ * machine. Only the exact string "1" disables it; any other value keeps the
+ * default open behavior.
+ *
+ * @param {Record<string, string | undefined>} env  a process.env-shaped object
+ * @returns {boolean}
+ */
+function shouldAutoOpen(env) {
+  return env.PLOTLINK_OWS_NO_OPEN !== "1";
+}
+
+module.exports = { planStartup, shouldAutoOpen };

package/lib/genres.ts

@@ -0,0 +1,92 @@
+export const GENRES = [
+  "Romance",
+  "Fantasy",
+  "Science Fiction",
+  "Mystery",
+  "Thriller",
+  "Horror",
+  "Adventure",
+  "Historical Fiction",
+  "Contemporary Lit",
+  "Humor",
+  "Poetry",
+  "Non-Fiction",
+  "Fanfiction",
+  "Short Story",
+  "Paranormal",
+  "Werewolf",
+  "LGBTQ+",
+  "New Adult",
+  "Teen Fiction",
+  "Diverse Lit",
+  "Others",
+] as const;
+
+export const LANGUAGES = [
+  "English",
+  "Chinese",
+  "Korean",
+  "Japanese",
+  "Spanish",
+  "French",
+  "Hindi",
+  "Arabic",
+  "Portuguese",
+  "Russian",
+  "Others",
+] as const;
+
+export const CONTENT_TYPES = ["fiction", "cartoon"] as const;
+
+export type Genre = (typeof GENRES)[number];
+export type Language = (typeof LANGUAGES)[number];
+export type ContentType = (typeof CONTENT_TYPES)[number];
+
+/**
+ * Punctuation/spacing/case-insensitive key for matching a free-form genre label
+ * to a canonical value. Strips everything but letters, digits and `+` (so
+ * `LGBTQ+` survives), which collapses `Sci-Fi`, `sci fi`, `SciFi` → `scifi` and
+ * `Science Fiction` / `science-fiction` → `sciencefiction`.
+ */
+function genreKey(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9+]/g, "");
+}
+
+const CANONICAL_GENRE_BY_KEY: Record<string, Genre> = Object.fromEntries(
+  GENRES.map((g) => [genreKey(g), g]),
+) as Record<string, Genre>;
+
+/**
+ * Common natural-language genre aliases → canonical PlotLink value (#412). Keyed
+ * by `genreKey`, so each entry already covers punctuation/spacing/case variants
+ * (e.g. the `scifi` key matches `Sci-Fi`, `Sci Fi`, `SciFi`). Canonical labels and
+ * their punctuation variants (e.g. `non fiction` → `Non-Fiction`) are handled by
+ * `CANONICAL_GENRE_BY_KEY` and don't need an alias here.
+ */
+const GENRE_ALIAS_BY_KEY: Record<string, Genre> = {
+  scifi: "Science Fiction",
+  sf: "Science Fiction",
+  comedy: "Humor",
+  humour: "Humor",
+  ya: "Teen Fiction",
+  youngadult: "Teen Fiction",
+  lgbt: "LGBTQ+",
+  lgbtq: "LGBTQ+",
+  "lgbtqia+": "LGBTQ+",
+  historical: "Historical Fiction",
+  scary: "Horror",
+};
+
+/**
+ * Map a free-form genre label to its canonical PlotLink value, or `null` if it
+ * can't be resolved (#412). PlotLink's metadata update rejects non-canonical
+ * genres (e.g. `Sci-Fi` → `Invalid genre`), which once left a published pilot
+ * `UNCATEGORIZED`; callers normalize through this before sending metadata and
+ * surface a clear local error when it returns `null`. Empty/blank input → `null`.
+ */
+export function canonicalizeGenre(input: string | null | undefined): Genre | null {
+  if (!input) return null;
+  const key = genreKey(input.trim());
+  if (!key) return null;
+  return CANONICAL_GENRE_BY_KEY[key] ?? GENRE_ALIAS_BY_KEY[key] ?? null;
+}

package/package.json

@@ -1,16 +1,53 @@
 {
   "name": "plotlink-ows",
-  "version": "1.0.32",
+  "version": "1.2.94",
+  "packageManager": "npm@10.9.8",
+  "engines": {
+    "node": "20.x",
+    "npm": "10.x"
+  },
   "bin": {
-    "plotlink-ows": "./bin/plotlink-ows.js"
+    "plotlink-ows": "bin/plotlink-ows.js"
   },
   "files": [
     "bin/",
     "app/",
     "lib/ows/",
+    "lib/genres.ts",
     "packages/",
     "public/",
-    "scripts/"
+    "scripts/",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.test.js",
+    "!**/*.test.jsx",
+    "!**/*.test.mjs",
+    "!**/*.spec.ts",
+    "!**/*.spec.tsx",
+    "!**/*.spec.js",
+    "!**/__tests__/**",
+    "!**/node_modules/**",
+    "!**/*.tgz",
+    "!**/.next/cache/**",
+    "!**/.turbo/**",
+    "!**/.vite/**",
+    "!**/.cache/**",
+    "!**/*.tsbuildinfo",
+    "!**/coverage/**",
+    "!**/.nyc_output/**",
+    "!**/__fixtures__/**",
+    "!**/fixtures/**",
+    "!**/*.fixture.*",
+    "!**/*.snap",
+    "!**/screenshot-*",
+    "!**/screenshots/**",
+    "!**/e2e-verify.*",
+    "!**/tmp/**",
+    "!**/temp/**",
+    "!**/*.log",
+    "!**/*.tmp",
+    "!**/*.bak",
+    "!**/*.swp"
   ],
   "workspaces": [
     "packages/*"
@@ -26,39 +63,31 @@
     "app:dev": "concurrently \"tsx watch app/server.ts\" \"vite --config app/vite.config.ts\"",
     "app:build": "vite build --config app/vite.config.ts",
     "app:start": "tsx app/server.ts",
+    "preflight": "node scripts/preflight.mjs",
+    "smoke:start": "node scripts/start-smoke.mjs",
     "prepublishOnly": "npm run app:build",
     "postinstall": "prisma generate --schema app/prisma/schema.prisma",
     "prisma:local": "prisma generate --schema app/prisma/schema.prisma && prisma db push --schema app/prisma/schema.prisma",
+    "prisma:sql": "node scripts/gen-schema-sql.mjs",
     "release:patch": "npm version patch && git push origin main --follow-tags && VERSION=$(node -p 'require(\"./package.json\").version') && gh release create \"v$VERSION\" --generate-notes --latest && npm publish",
     "release:minor": "npm version minor && git push origin main --follow-tags && VERSION=$(node -p 'require(\"./package.json\").version') && gh release create \"v$VERSION\" --generate-notes --latest && npm publish",
     "release:major": "npm version major && git push origin main --follow-tags && VERSION=$(node -p 'require(\"./package.json\").version') && gh release create \"v$VERSION\" --generate-notes --latest && npm publish"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1009.0",
-    "@hono/node-server": "^1.19.12",
+    "@hono/node-server": "^1.19.14",
     "@open-wallet-standard/core": "^1.2.4",
     "@prisma/client": "^6.19.3",
     "@supabase/supabase-js": "^2.99.1",
-    "@xterm/addon-fit": "^0.11.0",
-    "@xterm/addon-serialize": "^0.14.0",
-    "@xterm/xterm": "^6.0.0",
     "dotenv": "^17.4.0",
-    "hono": "^4.12.10",
+    "hono": "^4.12.23",
     "node-pty": "^1.2.0-beta.12",
     "prisma": "^6.19.3",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "react-markdown": "^10.1.0",
-    "rehype-sanitize": "^6.0.0",
-    "remark-breaks": "^4.0.0",
-    "remark-gfm": "^4.0.1",
-    "tailwindcss": "^4",
     "tsx": "^4.21.0",
     "viem": "^2.47.2",
-    "vite": "^6.4.1",
-    "ws": "^8.20.0"
+    "ws": "^8.20.1"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1009.0",
     "@farcaster/miniapp-node": "^0.1.13",
     "@farcaster/miniapp-sdk": "^0.3.0",
     "@farcaster/miniapp-wagmi-connector": "^2.0.0",
@@ -77,13 +106,24 @@
     "@types/ws": "^8.18.1",
     "@vercel/analytics": "^2.0.1",
     "@vitejs/plugin-react": "^4.7.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/xterm": "^6.0.0",
     "concurrently": "^9.2.1",
     "eslint": "^9",
-    "eslint-config-next": "16.1.6",
+    "eslint-config-next": "16.2.6",
     "jsdom": "^27.0.1",
-    "next": "16.1.6",
+    "next": "16.2.6",
     "ox": "^0.14.8",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-markdown": "^10.1.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "tailwindcss": "^4",
     "typescript": "^5",
+    "vite": "^6.4.3",
     "vitest": "^3.2.4",
     "wagmi": "^2.19.5"
   }

package/scripts/gen-schema-sql.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Regenerate app/prisma/schema.sql from app/prisma/schema.prisma (#484).
+//
+// The installed app applies this committed DDL at startup via the Prisma client
+// (app/lib/apply-schema.ts) instead of running `prisma db push`, so the native
+// Prisma schema-engine is never needed at runtime. Run this (and commit the
+// result) after ANY change to schema.prisma:  npm run prisma:sql
+//
+// This uses the schema-engine via `prisma migrate diff` — that's fine here
+// because it runs at DEV/build time on a developer machine, not at user runtime.
+
+import { execFileSync } from "node:child_process";
+import { writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = join(root, "app", "prisma", "schema.prisma");
+const outPath = join(root, "app", "prisma", "schema.sql");
+
+// Resolve the local Prisma CLI (same robust resolution the runtime once used).
+const requireFrom = createRequire(join(root, "__resolver__.js"));
+const prismaPkg = requireFrom.resolve("prisma/package.json");
+const pkg = JSON.parse(readFileSync(prismaPkg, "utf8"));
+const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin.prisma;
+const prismaCli = join(dirname(prismaPkg), binRel);
+
+const ddl = execFileSync(
+  process.execPath,
+  [prismaCli, "migrate", "diff", "--from-empty", "--to-schema-datamodel", schemaPath, "--script"],
+  { encoding: "utf8" },
+).trim();
+
+const header = [
+  "-- Canonical SQLite DDL for the local writer database.",
+  "-- GENERATED from app/prisma/schema.prisma — do not edit by hand.",
+  "-- Regenerate after any schema change:  npm run prisma:sql",
+  "--",
+  "-- Applied idempotently at startup via the Prisma client's library query engine",
+  "-- (app/lib/apply-schema.ts) so the installed package never invokes the native",
+  "-- Prisma schema-engine (`prisma db push`), which fails to spawn in some packed",
+  "-- prod-only environments (#484, EPIC #465).",
+  "",
+  "",
+].join("\n");
+
+writeFileSync(outPath, header + ddl + "\n");
+console.log(`Wrote ${outPath}`);

package/scripts/package-hygiene.mjs

@@ -0,0 +1,116 @@
+// Suspicious-file detection for the release preflight (#466, EPIC #465).
+//
+// Any packed file whose path matches one of these rules must NEVER ship in the
+// published `plotlink-ows` package. The package.json `files` allowlist already
+// excludes them (negation patterns); this is the preflight's belt-and-suspenders
+// detection so a regression is caught before publish. Keep the two in sync.
+
+export const SUSPICIOUS_RULES = [
+  { re: /(^|\/)node_modules\//, label: "bundled node_modules" },
+  { re: /\.(test|spec)\.[cm]?[jt]sx?$/, label: "test/spec file" },
+  { re: /(^|\/)(__fixtures__|fixtures)\/|\.fixture\./, label: "test fixture" },
+  { re: /\.snap$/, label: "test snapshot" },
+  { re: /(^|\/)e2e[-/]/, label: "e2e/test tooling" },
+  { re: /\.tgz$/, label: "packed tarball" },
+  { re: /(^|\/)(\.next\/cache|\.turbo|\.vite|\.cache|coverage|\.nyc_output)\//, label: "build/coverage cache" },
+  { re: /(^|\/)screenshots?\/|(^|\/)screenshot-/, label: "screenshot/marketing image" },
+  { re: /(^|\/)(tmp|temp)\/|\.(log|tmp|bak|swp)$/, label: "temp/log file" },
+  { re: /(^|\/)\.env(\..+)?$|\.(pem|key)$/, label: "possible secret/credential file" },
+];
+
+// The runtime files the published package MUST contain. A `files`-allowlist
+// change that drops one of these fails the preflight (#468). `app/web/dist` is
+// required because the CLI serves the prebuilt web UI from it.
+export const REQUIRED_PACK_FILES = [
+  "package.json",
+  "README.md",
+  "LICENSE",
+  "bin/plotlink-ows.js",
+  // The bin requires this in-package helper at runtime (start-path boundary
+  // planner); `files` ships all of `bin/`, but listing it here fails preflight
+  // if a future exclusion drops it (#470).
+  "bin/startup-plan.cjs",
+  "app/server.ts",
+  // Imported by app/server.ts at boot to apply the local SQLite schema without
+  // the native Prisma schema-engine (#484).
+  "app/lib/apply-schema.ts",
+  // The committed DDL apply-schema reads at startup — the installed app applies
+  // this instead of running `prisma db push` (#484).
+  "app/prisma/schema.sql",
+  "app/prisma/schema.prisma",
+  "app/web/dist/index.html",
+  // Root-lib file the server runtime imports at boot (publish route →
+  // `../../lib/genres`); `files` packs only `lib/ows/`, so it must be listed
+  // explicitly or the published CLI fails to start (#469).
+  "lib/genres.ts",
+];
+
+// The published OWS CLI runtime install path (`dependencies`). EPIC #465 keeps
+// this set MINIMAL — only packages the CLI actually loads at runtime (the server
+// in `app/`, the `bin/` wizard, and the runtime helpers in `lib/`). Web-app
+// (`src/`), build-time, and direct-upload-only packages belong in
+// `devDependencies` (see DEPENDENCIES.md): React/Vite/etc. (#469) and
+// `@aws-sdk/client-s3` (#471 — OWS uploads go through the PlotLink API, so the
+// S3/Filebase client is web-app-only). A new entry here must be a genuine OWS
+// runtime import; add it consciously (and document it) rather than by accident.
+export const ALLOWED_RUNTIME_DEPS = [
+  "@hono/node-server",
+  "@open-wallet-standard/core",
+  "@prisma/client",
+  "@supabase/supabase-js",
+  "dotenv",
+  "hono",
+  "node-pty",
+  "prisma",
+  "tsx",
+  "viem",
+  "ws",
+];
+
+/**
+ * Runtime `dependencies` that are NOT in the OWS runtime allowlist — i.e. a
+ * web-app/build-time/upload-only package that leaked into the published install
+ * path (#471, EPIC #465). An empty array means the install path is clean.
+ */
+export function findRuntimeDepLeaks(pkg) {
+  const allowed = new Set(ALLOWED_RUNTIME_DEPS);
+  return Object.keys(pkg.dependencies ?? {}).filter((d) => !allowed.has(d));
+}
+
+/** Return the REQUIRED_PACK_FILES that are NOT in the packed path list. */
+export function findMissingRequired(paths) {
+  const set = new Set(paths);
+  return REQUIRED_PACK_FILES.filter((req) => !set.has(req));
+}
+
+/**
+ * Return `[{ label, path }]` for every path matching a suspicious rule (first
+ * match wins per path). An empty array means the file list is clean.
+ */
+export function findSuspicious(paths) {
+  const out = [];
+  for (const path of paths) {
+    for (const rule of SUSPICIOUS_RULES) {
+      if (rule.re.test(path)) { out.push({ label: rule.label, path }); break; }
+    }
+  }
+  return out;
+}
+
+/**
+ * The files a freshly-installed package MUST contain to function: the bin(s),
+ * the app entrypoints, AND every file the install LIFECYCLE references — notably
+ * the `--schema <path>` the `postinstall` runs `prisma generate` against (#466,
+ * re1). The smoke test asserts these are present, so a `files`-allowlist
+ * regression that drops a postinstall prerequisite fails the preflight instead
+ * of silently breaking a real `npm install` of the published tarball.
+ */
+export function requiredInstalledFiles(pkg) {
+  const required = ["package.json", "app/server.ts", "app/web/dist/index.html"];
+  const binPaths = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin ?? {});
+  for (const b of binPaths) if (b) required.push(String(b).replace(/^\.?\//, ""));
+  // Every `--schema <path>` referenced by the postinstall lifecycle.
+  const postinstall = pkg.scripts?.postinstall ?? "";
+  for (const m of postinstall.matchAll(/--schema[= ]+(\S+)/g)) required.push(m[1]);
+  return [...new Set(required)];
+}