tachlon 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# tachlon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Gantt chart for the browser. The engine is a WebAssembly file and the chart draws on the GPU (WebGPU, or WebGL2 where WebGPU is missing). It needs no Rust toolchain.
+
+Tachlon is proprietary software with a free trial: the chart works on any page, and shows a small "Unlicensed" mark outside localhost until you pass a license key (see [The watermark and `licenseKey`](#the-watermark-and-licensekey) and [License](#license)).
+
+## Install
+
+```sh
+npm install tachlon
+```
+
+The package holds the chart's script, its stylesheet, TypeScript declarations, the engine file `app_bg.wasm` beside the script, and the task data's schema. It runs in the browser: use it from a bundler such as Vite or Next.js, or serve the files as they are.
+
+## Quick start
+
+Give `mount` an element and the tasks to draw. The element is a `div` with the class `gantt` and a box with a height:
+
+```html
+<div id="chart" class="gantt" style="width: 800px; height: 300px"></div>
+```
+
+```js
+import { mount } from "tachlon";
+import "tachlon/gantt.css";
+
+const tasks = [
+  { id: 1, name: "Design", start: "2026-11-02", duration: 3 },
+  { id: 2, name: "Build", start: "2026-11-05", duration: 5 },
+  { id: 3, name: "Ship", start: "2026-11-12", duration: 1 },
+];
+const links = [{ from: 1, to: 2 }, { from: 2, to: 3 }];
+
+const chart = await mount(document.getElementById("chart"), { tasks, links });
+chart.on("select", ({ task }) => console.log("picked task", task));
+```
+
+`mount` returns a promise of the chart. `start` is `YYYY-MM-DD`. `duration` counts working days. A link is finish-to-start unless it gives a `type` of `"SS"`, `"FF"` or `"SF"`.
+
+`forceWebgl: true` draws with WebGL2 and never tries WebGPU. If WebGPU fails, the chart moves to WebGL2 by itself and fires an `error` event.
+
+`mount` rejects with a `MountError` if the first schedule cannot be read or the first frame cannot start. Its `message` says why, and its `fix` says what to do.
+
+## Use it in React
+
+`tachlon/react` is a React component, `Gantt`, from the same package. It takes `schedule`, `tasks`, `links`, `licenseKey` and `forceWebgl` as props (to load the engine from another address with `wasmUrl`, call `mount` yourself) and the chart's events as callbacks (`onSelect`, `onMove` and the rest). It mounts the chart when it mounts and calls `destroy()` when it unmounts. React 18 or later is a peer dependency that you install yourself; an app with no React needs none.
+
+```jsx
+import { Gantt } from "tachlon/react";
+import "tachlon/gantt.css";
+
+// Keep `tasks` and `links` the same objects between renders: the chart starts again when they change.
+<Gantt tasks={tasks} links={links} style={{ width: 800, height: 300 }} onSelect={({ task }) => console.log("picked task", task)} />;
+```
+
+## Load a P6 or MS Project file
+
+The chart opens Primavera P6 XER files, MS Project XML files, and its own `.gantt` documents. Pass `chart.load` an object with the `File` as its `file` property:
+
+```js
+const result = await chart.load({ file });
+if (!result.ok) console.error(result.error);
+```
+
+`load` returns a result and never throws; a bad file leaves the schedule as it was. To start a chart from a file, pass it to `mount` as `schedule` instead of `tasks`: `mount(element, { schedule: file })`. `chart.open(file)` replaces the schedule the same way and also takes an `OpenOptions` for a file with several projects.
+
+`chart.toDocument()` returns the open schedule as a document that `chart.load({ document })` reads back. `chart.exportXer()` and `chart.exportMspdi()` return the open schedule as a P6 XER or MS Project XML file (`bytes`, and `leftOut`, one line for each thing the format cannot carry).
+
+Already have DHTMLX Gantt or Bryntum Gantt data? `fromDhtmlx(data)` and `fromBryntum(data)` read it into a result whose `document` is what `chart.load({ document })` takes (`fromBryntum` returns `{ ok: false, error }` when it cannot read the data). `fromTasks({ tasks, links })` does the same for plain tasks and links, and `validate({ tasks, links })` names each problem in them by path with a fix.
+
+## Add it to a Vite app
+
+Inside a Vite project (with or without React), `npx tachlon init` installs the package with the project's own manager (found from its lockfile, else npm) and writes a chart file beside your code: `src/tachlon-chart.js`, `.ts`, `.jsx` or `.tsx`, or the same name at the project folder when there is no `src/`. The file mounts the chart with three sample tasks, imports `tachlon/gantt.css`, and removes the chart when its page or component goes away. The command prints the one line to add to a page and the command to start the app. It writes new files only: never an existing page, Vite config, lockfile or tsconfig.
+
+- `--dry-run` prints the plan and writes nothing.
+- `--dir <folder>` names the project folder; without it the nearest `package.json` at or above the working folder is the project.
+- `--spec <spec>` installs that spec (a tarball path, a version range) instead of this package's own version; `--no-install` installs nothing.
+- `--plain` writes the module that needs no framework (a function that takes the chart's `div`), for a project whose bundler `init` does not know.
+
+A second run changes nothing and says so. `init` exits 2 and writes nothing when there is no `package.json`, when the folder is a workspace root and `--dir` is not given, when the project is neither Vite nor Next.js (it names the bundler it found, or says there is none, and offers `--plain`), when a file it would write already exists with other contents (it names the path), or when the install fails. In a Next.js project (an `app/` or `pages/` folder, in the project folder or in `src/`), `init` instead writes the chart as a client component, `components/tachlon-chart.jsx` or `.tsx` beside that folder, and copies the installed engine to `public/app_bg.wasm`, which the component loads with `wasmUrl: "/app_bg.wasm"`; it exits 2 when there is neither folder, or when the package is not in `node_modules` to copy the engine from.
+
+## Check an install with `tachlon doctor`
+
+When the chart does not draw, run `npx tachlon doctor` in the project. It reads the project and writes nothing in it. It prints one line for each check (`ok`, `FAIL` or `skip`) and a one-sentence `fix:` under each failure and under each `skip` line. `--dir <folder>` names the project folder; a workspace root needs it. The checks, with the code each failure carries:
+
+- `package.json` lists the package and `node_modules` holds one copy of it: `NOT_LISTED`, `NOT_INSTALLED`, `MANY_COPIES`.
+- The installed engine file `dist-lib/app_bg.wasm` is there, starts with `\0asm`, and has the size the package's build recorded: `ENGINE_MISSING`, `ENGINE_NOT_WASM`, `ENGINE_UNRECORDED`, `ENGINE_SIZE`.
+- A source file imports `tachlon/gantt.css`: `STYLESHEET_MISSING`.
+- In a Next app, the engine copy `public/app_bg.wasm` that `init` writes is the installed engine, not one left from an older version: `ENGINE_COPY_MISSING`, `ENGINE_COPY_STALE`.
+- A Content-Security-Policy in the project's config (`next.config.*`, `vercel.json`, `netlify.toml`, `public/_headers`, `index.html`, `public/index.html`) lets the browser compile the engine: `CSP_WASM_EVAL` when its `script-src` (or `default-src`) lacks `'wasm-unsafe-eval'` (or `'unsafe-eval'`). A report-only policy blocks nothing and is skipped; with no policy found there is no finding.
+
+`--url <page>` also fetches the page that mounts the chart (two requests; a page it cannot fetch, or that does not answer 200, is exit 2) and checks what the site serves. The policy in its `Content-Security-Policy` header and `<meta>` tags gets the same `CSP_WASM_EVAL` check, and `CSP_CONNECT_SRC` when the engine is on another origin that `connect-src` does not allow. The engine is the `.wasm` address the page's HTML names, or `/app_bg.wasm` in a Next app. It must answer 200 (`ENGINE_FETCH`), start with `\0asm` (`ENGINE_NOT_WASM`) and have the type `application/wasm` (`ENGINE_CONTENT_TYPE`), and in a Next app it must equal the installed engine (`ENGINE_URL_STALE`). Outside Next, a page that names no `.wasm` address gets `ENGINE_URL_SKIPPED`: a Vite build names its hashed engine file only in a script, so open the page in a browser and request the address from its network panel.
+
+`--data <file>` also runs `validate()` on a task data file, with one `DATA_INVALID` finding for each problem, or `DATA_NOT_JSON` when the file is not JSON.
+
+`doctor` also asks a real browser which graphics path the chart will use, because a Node process has no WebGPU or WebGL2 of its own. It opens a page of its own, headless, in the first Chrome, Edge or Chromium it finds (`TACHLON_BROWSER` names one; otherwise it looks for `google-chrome`, `chromium` and `microsoft-edge` on the path, then for the Chrome and Edge apps on a Mac) and reports one finding. The chart tries WebGPU first and falls back to WebGL2, and so does the page:
+
+- `GPU_WEBGPU` (`ok`) when the browser has a WebGPU adapter, with the adapter's name.
+- `GPU_WEBGL2` (`ok`) when it has no WebGPU adapter but has WebGL2, with the renderer's name.
+- `GPU_NONE` (`FAIL`) when it has neither, the case where `mount` rejects with `TACHLON_GPU_NONE`; the `fix:` line says what to try.
+
+That is the browser on the machine that runs `doctor`, not the one a visitor uses. A headless browser on a machine with no graphics card may name a software renderer such as SwiftShader, which is the answer, not a fault. When no browser is found, or the one found fails to answer, the line reads `skip GPU_SKIPPED` with the reason, and it does not fail the run: open the page in a browser and read the error `mount` rejects with.
+
+Exit 0 means no check failed, 1 means at least one did, and 2 means `doctor` could not run: no `package.json`, a workspace root without `--dir`, a file it could not read, or a flag it does not know. This run is from a fixture whose engine file was deleted from `node_modules`:
+
+```text
+doctor in .
+  ok   INSTALLED: tachlon 0.1.0 at node_modules/tachlon
+  ok   ONE_COPY: one copy is installed
+  FAIL ENGINE_MISSING: node_modules/tachlon/dist-lib/app_bg.wasm is missing
+       fix: Delete the package from node_modules and install it again with `npm install`, and stop any cleanup step that deletes .wasm files.
+  ok   STYLESHEET_OK: a source file imports tachlon/gantt.css
+  ok   GPU_WEBGL2: the browser has no WebGPU adapter but has WebGL2 (ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)), so the chart draws with WebGL2
+1 problem found.
+```
+
+Do the `fix:`, then run `doctor` again; a clean run ends with `No problems found.` and exit 0. `--json` prints `{ "dir": ..., "findings": [...] }` instead, with the same exit code. Each finding has `code`, `status` (`"pass"`, `"fail"` or `"skipped"`), `what`, and `fix` (empty on a pass), so a script or an assistant can read the failures without parsing text.
+
+## The stylesheet
+
+`import "tachlon/gantt.css"` once in your app. The chart's colours, bar shape, row height and type are CSS tokens, in light and dark, that your own CSS can set.
+
+## The schema
+
+`tachlon/schema.json` is the JSON Schema of the task data `mount` reads (`tasks` and `links`). Read it from `node_modules/tachlon/dist-lib/schema.json`, or give it to a tool or an assistant that writes task data.
+
+## Stop the chart
+
+`chart.destroy()` stops the frame loop, frees the engine, and empties the element. Call it when the page removes the chart. It is safe to call twice; every other method throws once it has run.
+
+## The engine file
+
+The script loads `app_bg.wasm` from the address beside itself. Serve it with status 200 as `application/wasm`. To serve it from elsewhere, pass `wasmUrl` to `mount`. Under a Content-Security-Policy, add `'wasm-unsafe-eval'` to `script-src`.
+
+## The watermark and `licenseKey`
+
+A page served from localhost or `file:` is always licensed. On any other origin the chart is in trial: a small "Unlicensed" mark shows in its corner, and the chart works as before. Pass `licenseKey` to `mount` to license a chart:
+
+```js
+const chart = await mount(element, { tasks, licenseKey: "<your key>" });
+```
+
+The root element's `data-tachlon-license` reads `"licensed"` or `"trial"`. The key check accepts no key yet, so the mark stays on every non-local page for now.
+## License
+
+Copyright Inner Stack Labs. All rights reserved. Tachlon is proprietary software, not open source, and the package's `license` field is `UNLICENSED`.
+
+- **Trial.** You may install and run Tachlon to evaluate it. Outside localhost and `file:` pages the chart shows the "Unlicensed" mark.
+- **Production.** Using Tachlon in a product that real users reach needs a license key from Inner Stack Labs.
+- **Everything else.** You may not copy, modify, redistribute, sublicense or reverse engineer Tachlon, or use it to build a competing product, except as a license key's terms allow.
+
+To buy a license key, or to ask what a use needs, write to hello@tachlon.com. Tachlon is provided as is, with no warranty.
+
+## Types and API reference
+
+The declarations (`dist-lib/types`, the package's `types` entry) cover the whole API, and every method carries its documentation comment. The API reference is part of the Tachlon guide, which is invite-only for now: <https://app.tachlon.com/book/>. There is no public documentation site yet.

package/dist-lib/adapters/validate.js

@@ -0,0 +1,159 @@
+// `validate(data)` (tl#1249): check plain task data before `fromTasks` reads it, and name every problem: the path in the
+// plain field names, what was expected, what was there, and one sentence for the fix. It states the same shape as
+// `plain.schema.json`, plus what a schema cannot: ids that repeat, and a parent or link that names a missing task. A pure
+// function of its input.
+const MAX = 50;
+const DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})?$/;
+const TYPES = ["FS", "SS", "FF", "SF"];
+/** What `fromTasks` throws for data `validate` refuses; `issues` is the list, `message` is the list as lines. */
+export class PlainDataError extends Error {
+    issues;
+    constructor(issues) {
+        const count = issues.length >= MAX ? `${MAX} or more problems (the first ${MAX})` : `${issues.length} problem${issues.length === 1 ? "" : "s"}`;
+        super(`Task data has ${count}:\n${issues.map((i) => `  ${i.path || "data"}: expected ${i.expected}, got ${i.got}. ${i.fix}`).join("\n")}`);
+        this.name = "PlainDataError";
+        this.issues = issues;
+    }
+}
+const TASK = {
+    id: { kind: "id", required: true },
+    name: { kind: "text", required: true },
+    start: { kind: "date", required: true },
+    end: { kind: "date" },
+    duration: { kind: "number", min: 0 },
+    parent: { kind: "id" },
+    progress: { kind: "number", min: 0, max: 100 },
+};
+const LINK = {
+    from: { kind: "id", required: true },
+    to: { kind: "id", required: true },
+    type: { kind: "type" },
+    lag: { kind: "number" },
+};
+const EXAMPLE = { id: '"site" or 7', text: '"Site works"', date: '"2026-03-02" or "2026-03-02T08:00"', number: "5", type: '"FS"' };
+function show(v) {
+    if (v === undefined)
+        return "nothing";
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    if (typeof v === "object")
+        return "an object";
+    const s = JSON.stringify(v);
+    return `${typeof v} ${s.length > 40 ? `${s.slice(0, 37)}...` : s}`;
+}
+const isId = (v) => typeof v === "string" || typeof v === "number";
+/** Whether `v` is a good value for a field of this kind: the cheap test, so a good value allocates nothing. */
+function fine(f, v) {
+    switch (f.kind) {
+        case "id":
+            return typeof v === "string" || typeof v === "number";
+        case "text":
+            return typeof v === "string";
+        case "date":
+            return typeof v === "string" && DATE.test(v);
+        case "type":
+            return typeof v === "string" && TYPES.includes(v);
+        case "number":
+            return typeof v === "number" && Number.isFinite(v) && (f.min === undefined || v >= f.min) && (f.max === undefined || v <= f.max);
+    }
+}
+/** The problem with one field's value. */
+function problem(name, f, v) {
+    const as = (expected) => ({ expected, fix: `Write ${name} as ${expected}, for example ${EXAMPLE[f.kind]}.` });
+    switch (f.kind) {
+        case "id":
+            return as("text or a number");
+        case "text":
+            return as("text");
+        case "date":
+            return as("a date as YYYY-MM-DD or YYYY-MM-DDTHH:mm");
+        case "type":
+            return { expected: 'one of "FS", "SS", "FF", "SF"', fix: 'Use "FS" (finish to start), "SS", "FF" or "SF", or leave type out for FS.' };
+        case "number": {
+            if (typeof v !== "number" || !Number.isFinite(v))
+                return as("a number");
+            const range = f.max === undefined ? `${f.min} or more` : `${f.min} to ${f.max}`;
+            return { expected: `a number from ${range}`, fix: `Use a value of ${range} for ${name}.` };
+        }
+    }
+}
+const TASK_ENTRIES = Object.entries(TASK);
+const LINK_ENTRIES = Object.entries(LINK);
+/** Check plain task data and name every problem, up to 50. */
+export function validate(data) {
+    const { issues } = inspect(data);
+    return issues.length === 0 ? { ok: true } : { ok: false, issues };
+}
+/** `validate`'s one walk of the data: the problems, and the index of each task by `String(id)` for the reader to use. */
+export function inspect(data) {
+    const issues = [];
+    const ids = new Map();
+    const add = (path, expected, got, fix) => {
+        if (issues.length < MAX)
+            issues.push({ path, expected, got, fix });
+    };
+    const fields = (item, path, table) => {
+        if (typeof item !== "object" || item === null || Array.isArray(item))
+            return add(path, "an object", show(item), "Write each entry as an object in braces, with its fields.");
+        const rec = item;
+        for (const [name, f] of table) {
+            const v = rec[name];
+            if (v === undefined) {
+                if (f.required)
+                    add(`${path}.${name}`, `a ${name}`, "nothing", `Add ${name}, for example ${EXAMPLE[f.kind]}.`);
+            }
+            else if (!fine(f, v)) {
+                const p = problem(name, f, v);
+                add(`${path}.${name}`, p.expected, show(v), p.fix);
+            }
+        }
+    };
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        add("", 'an object with a "tasks" array', show(data), 'Pass { "tasks": [...], "links": [...] }.');
+        return { issues, ids };
+    }
+    const { tasks, links } = data;
+    if (!Array.isArray(tasks))
+        add("tasks", "an array of tasks", show(tasks), 'Pass the tasks as an array: { "tasks": [{ "id": 1, "name": "Task", "start": "2026-03-02" }] }.');
+    if (links !== undefined && !Array.isArray(links))
+        add("links", "an array of links", show(links), 'Pass links as an array: [{ "from": 1, "to": 2 }], or leave links out.');
+    if (Array.isArray(tasks)) {
+        for (let i = 0; i < tasks.length; i++) {
+            if (!(i in tasks))
+                continue;
+            const t = tasks[i];
+            fields(t, `tasks[${i}]`, TASK_ENTRIES);
+            const id = t?.id;
+            if (!isId(id))
+                continue;
+            const first = ids.get(String(id));
+            if (first === undefined)
+                ids.set(String(id), i);
+            else
+                add(`tasks[${i}].id`, "an id no other task has", `${show(id)}, also tasks[${first}].id`, "Give each task its own id.");
+        }
+        for (let i = 0; i < tasks.length; i++) {
+            if (!(i in tasks))
+                continue;
+            const parent = tasks[i]?.parent;
+            if (isId(parent) && !ids.has(String(parent)))
+                add(`tasks[${i}].parent`, "the id of a task in tasks", show(parent), "Use the id of a task in tasks, or leave parent out.");
+        }
+    }
+    if (Array.isArray(links)) {
+        for (let i = 0; i < links.length; i++) {
+            if (!(i in links))
+                continue;
+            const l = links[i];
+            fields(l, `links[${i}]`, LINK_ENTRIES);
+            for (const end of ["from", "to"]) {
+                const v = l?.[end];
+                if (Array.isArray(tasks) && isId(v) && !ids.has(String(v)))
+                    add(`links[${i}].${end}`, "the id of a task in tasks", show(v), `Use the id of a task in tasks for ${end}, or remove this link.`);
+            }
+        }
+    }
+    return { issues, ids };
+}

package/dist-lib/cli/args.js

@@ -0,0 +1,36 @@
+// The command line's arguments: one command, and flags only (no prompts: the caller is usually an assistant).
+/** The flags that take a value: the field each fills and what it needs, for the sentence when the value is missing. */
+const VALUED = { "--dir": ["dir", "a folder"], "--spec": ["spec", "a package spec"], "--data": ["data", "a data file"], "--url": ["url", "a page address"] };
+/** The arguments `argv` holds, or the sentence that says why they are not valid. */
+export function parseArgs(argv) {
+    const args = { command: undefined, dryRun: false, json: false, dir: undefined, spec: undefined, data: undefined, url: undefined, install: true, plain: false, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const [flag, inline] = argv[i].split(/=(.*)/s, 2);
+        if (flag === "--dry-run")
+            args.dryRun = true;
+        else if (flag === "--json")
+            args.json = true;
+        else if (flag === "--no-install")
+            args.install = false;
+        else if (flag === "--plain")
+            args.plain = true;
+        else if (flag === "--help" || flag === "-h")
+            args.help = true;
+        else if (flag === "--version" || flag === "-v")
+            args.version = true;
+        else if (Object.hasOwn(VALUED, flag)) {
+            const [key, needs] = VALUED[flag];
+            const value = inline ?? argv[++i];
+            if (!value || value.startsWith("-"))
+                return { error: `${flag} needs ${needs}` };
+            args[key] = value;
+        }
+        else if (flag.startsWith("-"))
+            return { error: `unknown flag ${flag}` };
+        else if (args.command === undefined)
+            args.command = flag;
+        else
+            return { error: `unexpected argument ${flag}` };
+    }
+    return args;
+}

package/dist-lib/cli/csp.js

@@ -0,0 +1,68 @@
+// The Content-Security-Policy a page needs for the engine to load: where `doctor` finds a policy (the project's config, a served page) and whether it lets the engine compile and connect.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The files that carry a policy in the frameworks and hosts the command line knows, and how each holds it: Next's headers, Vercel and Netlify (a string), Netlify's `_headers` (a line), a page (a meta tag). */
+const CONFIG_FILES = [["next.config.js", "string"], ["next.config.mjs", "string"], ["next.config.cjs", "string"], ["next.config.ts", "string"], ["vercel.json", "string"], ["netlify.toml", "string"], ["public/_headers", "headers"], ["index.html", "html"], ["public/index.html", "html"]];
+/** A string that holds (a piece of) a policy: it names a `*-src` directive. The key beside it does not matter, so a policy kept in a constant is found too. Only a template literal runs over lines. */
+const STRING = /(["'])((?:(?!\1)[^\n])*?\b[a-z]+-src\s(?:(?!\1)[^\n])*)\1|`([^`]*?\b[a-z]+-src\s[^`]*)`/g;
+const HEADERS_LINE = /^[ \t]+Content-Security-Policy:[ \t]*(.+)$/gim;
+const META = /<meta\b[^>]*?http-?equiv=["']Content-Security-Policy["'][^>]*>/gi;
+const flat = (s) => s.replace(/\s+/g, " ").trim();
+/** The policies in the `<meta http-equiv>` tags of `html`. */
+export function metaPolicies(html, source) {
+    return [...html.matchAll(META)].flatMap(([tag]) => {
+        const content = /\bcontent=(["'])(.*?)\1/is.exec(tag);
+        return content ? [{ source, text: flat(content[2]) }] : [];
+    });
+}
+/** The policies the project's config files hold as an enforced header or meta tag; a report-only one blocks nothing and is skipped. */
+export function configPolicies(dir) {
+    return CONFIG_FILES.filter(([f]) => existsSync(join(dir, f))).flatMap(([file, kind]) => {
+        const text = readFileSync(join(dir, file), "utf8");
+        if (kind === "html")
+            return metaPolicies(text, file);
+        if (kind === "headers")
+            return [...text.matchAll(HEADERS_LINE)].map((m) => ({ source: file, text: flat(m[1]) }));
+        // The strings of one file are the pieces of one policy (an array joined with "; ", strings added across lines), so they are read as one.
+        const pieces = [...text.matchAll(STRING)].filter((m) => !/report-only/i.test(text.slice(Math.max(0, m.index - 80), m.index))).map((m) => flat(m[2] ?? m[3]));
+        return pieces.length > 0 ? [{ source: file, text: pieces.join("; ") }] : [];
+    });
+}
+/** The source list `policy` sets for `directive`, else for `default-src`; undefined when it sets neither (the policy puts no limit on it). */
+function sources(policy, directive) {
+    const set = new Map();
+    for (const part of policy.split(";")) {
+        const [name, ...list] = part.trim().split(/\s+/);
+        if (name && !set.has(name.toLowerCase()))
+            set.set(name.toLowerCase(), list);
+    }
+    return set.get(directive) ?? set.get("default-src");
+}
+/** Whether the browser may compile WebAssembly under `policy`: `script-src` (else `default-src`) holds `'wasm-unsafe-eval'` or `'unsafe-eval'`, or the policy sets neither. */
+export function allowsWasm(policy) {
+    const list = sources(policy, "script-src");
+    return list === undefined || list.some((s) => ["'wasm-unsafe-eval'", "'unsafe-eval'"].includes(s.toLowerCase()));
+}
+/** Whether `connect-src` (else `default-src`) lets a page at `page` request `target`, or the policy sets neither. */
+export function allowsConnect(policy, target, page) {
+    const list = sources(policy, "connect-src");
+    return list === undefined || list.some((s) => matches(s.toLowerCase(), target, page));
+}
+/** One source expression of a source list against `target`: `*`, `'self'`, a scheme (`https:`), or a host with an optional scheme, `*.` prefix and port. */
+function matches(source, target, page) {
+    if (source === "*")
+        return true;
+    if (source === "'self'")
+        return target.origin === page.origin;
+    if (source.endsWith(":"))
+        return target.protocol === source;
+    const m = /^(?:([a-z][a-z0-9+.-]*):\/\/)?(\*\.)?([^/:*]+)(?::(\d+|\*))?(?:\/.*)?$/.exec(source);
+    if (!m)
+        return false;
+    const [, scheme, wild, host, port] = m;
+    if (scheme !== undefined ? `${scheme}:` !== target.protocol : target.protocol !== page.protocol && target.protocol !== "https:")
+        return false;
+    if (port === undefined ? target.port !== "" : port !== "*" && port !== target.port)
+        return false;
+    return wild ? target.hostname.endsWith(`.${host}`) : target.hostname === host;
+}

package/dist-lib/cli/detect.js

@@ -0,0 +1,86 @@
+// What the command line reads from a project folder: where the project is, its package manager and its framework.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const OTHER_BUNDLERS = ["webpack", "parcel", "rollup", "esbuild", "@angular/cli", "astro", "@sveltejs/kit", "nuxt", "gatsby", "@remix-run/dev", "react-scripts"];
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["package-lock.json", "npm"],
+];
+/** A reason the command cannot run, in one sentence; `run` turns it into exit 2. */
+export class Refusal extends Error {
+}
+/** The JSON object in `file`, or a `Refusal` saying it cannot be read, is not JSON, or is not an object. */
+export function readJsonObject(file) {
+    const why = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s+/g, " ");
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        throw new Refusal(`${file} cannot be read: ${why(e)}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Refusal(`${file} is not valid JSON: ${why(e)}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Refusal(`${file} is not a JSON object`);
+    return value;
+}
+/** The nearest folder at or above `start` that holds a package.json, or undefined; with `exact`, only `start` itself. */
+export function findProjectDir(start, exact = false) {
+    for (let dir = resolve(start);; dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        if (exact || dirname(dir) === dir)
+            return undefined;
+    }
+}
+/** The manager `dir` names by a lockfile, else by its package.json's `packageManager`; undefined if neither. */
+function managerHere(dir, pkg) {
+    const locked = LOCKFILES.find(([file]) => existsSync(join(dir, file)));
+    if (locked)
+        return locked[1];
+    const named = pkg.packageManager?.split("@")[0];
+    return LOCKFILES.find(([, m]) => m === named)?.[1];
+}
+/** The manager of the nearest workspace root above `dir` (a `pnpm-workspace.yaml`, or a package.json with `workspaces`): its members share its lockfile. */
+function managerOfWorkspaceRoot(dir) {
+    for (let up = dirname(dir); up !== dir; dir = up, up = dirname(up)) {
+        let pkg = {};
+        try {
+            pkg = readJsonObject(join(up, "package.json"));
+        }
+        catch {
+            // no package.json here, or one that is not JSON: it is not a workspace root we can read
+        }
+        if (existsSync(join(up, "pnpm-workspace.yaml")) || pkg.workspaces !== undefined)
+            return managerHere(up, pkg);
+    }
+    return undefined;
+}
+function managerOf(dir, pkg) {
+    return managerHere(dir, pkg) ?? managerOfWorkspaceRoot(dir) ?? "npm";
+}
+/** What `dir` (a folder with a package.json) is: its manager, framework and where Next keeps its routes. */
+export function detect(dir) {
+    const pkg = readJsonObject(join(dir, "package.json"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const routerRoot = ["", "src"].find((r) => ["app", "pages"].some((f) => existsSync(join(dir, r, f))));
+    return {
+        dir,
+        manager: managerOf(dir, pkg),
+        framework: "next" in deps ? "next" : "react" in deps ? "react" : "none",
+        bundler: "next" in deps ? "next" : "vite" in deps ? "vite" : undefined,
+        otherBundler: OTHER_BUNDLERS.find((b) => b in deps),
+        routerRoot,
+        typescript: "typescript" in deps || existsSync(join(dir, "tsconfig.json")),
+        workspace: pkg.workspaces !== undefined || existsSync(join(dir, "pnpm-workspace.yaml")),
+    };
+}