@haystackeditor/cli 0.25.0 → 0.25.1

package/dist/capture/adapters/rails.js

@@ -132,6 +132,13 @@ export async function detectRails(ctx) {
         label: `Rails ${version?.version ?? '(unknown version)'}`,
         manifestAdapter: `rails@${version?.version ?? 'unknown'}`,
         blocked: blocked.length > 0 ? blocked.join('; ') : null,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: blocked.length > 0 ? blocked.join('; ') : null,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
         looked: [layoutsPath, repoPath(ctx, join(ctx.appDir, 'Gemfile.lock'))],
         staticDir: 'public',
         async integrate(tags) {

package/dist/capture/adapters/react-router.js

@@ -412,6 +412,13 @@ export async function detectReactRouter(ctx) {
         label,
         manifestAdapter: `${reactRouter ? 'react-router' : 'remix'}@${version.version}`,
         blocked: blocked.length > 0 ? blocked.join('; ') : null,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: blocked.length > 0 ? blocked.join('; ') : null,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
         looked,
         staticDir: 'public',
         integrate: tags => rootEdit(ctx, root, tags),

package/dist/capture/adapters/sveltekit.js

@@ -71,6 +71,13 @@ export async function detectSvelteKit(ctx) {
         label: `SvelteKit ${version.version}`,
         manifestAdapter: `sveltekit@${version.version}`,
         blocked: blocked.length > 0 ? blocked.join('; ') : null,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: blocked.length > 0 ? blocked.join('; ') : null,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
         looked: [templatePath, where, repoPath(ctx, join(ctx.appDir, routesDir))],
         staticDir: assets,
         async integrate(tags) {

package/dist/capture/adapters/vite.js

@@ -79,6 +79,13 @@ export async function detectVite(ctx) {
         label: `Vite ${version.version}${router ? ` with ${router}` : ''}`,
         manifestAdapter: `vite@${version.version}`,
         blocked: blocked.length > 0 ? blocked.join('; ') : null,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: blocked.length > 0 ? blocked.join('; ') : null,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
         looked: [indexPath, where, repoPath(ctx, srcDir)],
         staticDir: toPosix(posix.join(toPosix(root), toPosix(publicDir))),
         integrate: async (tags) => htmlEdit(index, tags, indexPath),
@@ -109,6 +116,13 @@ export async function detectStaticHtml(ctx) {
         label: 'a static HTML site',
         manifestAdapter: 'static-html',
         blocked: pages.length === 1 ? null : `the site has ${pages.length} HTML pages (${pages.slice(0, 5).join(', ')}${pages.length > 5 ? ', …' : ''}), each needing the tag`,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: pages.length === 1 ? null : `the site has ${pages.length} HTML pages (${pages.slice(0, 5).join(', ')}${pages.length > 5 ? ', …' : ''}), each needing the tag`,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
         looked: [indexPath],
         staticDir: '.',
         integrate: async (tags) => htmlEdit(index, tags, indexPath),

package/dist/capture/app-config.js

@@ -36,7 +36,8 @@ export function readCaptureConfig(appDir) {
     if (parsed.version !== CAPTURE_VERSION || strings.some(name => typeof parsed[name] !== 'string')
         || !CAPTURE_KEY_PATTERN.test(parsed.key) || !(parsed.adapter === null || typeof parsed.adapter === 'string')
         || !Array.isArray(parsed.origins) || !parsed.origins.every(origin => typeof origin === 'string')
-        || !Array.isArray(parsed.publish) || !parsed.publish.every(dir => typeof dir === 'string')) {
+        || !Array.isArray(parsed.publish) || !parsed.publish.every(dir => typeof dir === 'string')
+        || !(parsed.urlRewrites === undefined || parsed.urlRewrites === null || typeof parsed.urlRewrites === 'string')) {
         throw new Error(`${CAPTURE_CONFIG_PATH} is not a capture configuration init wrote; remove it and run \`haystack init\` again.`);
     }
     return parsed;

package/dist/capture/csp.js

@@ -11,7 +11,7 @@
  */
 import fg from 'fast-glob';
 import { readFileSync, statSync } from 'node:fs';
-import { extname, join } from 'node:path';
+import { extname, join, relative } from 'node:path';
 import { SAXParser } from 'parse5-sax-parser';
 import { CAPTURE_ORIGIN } from '../commands/capture-contract.js';
 import { keyName, parseFile, parseJsonLike, unwrapTs, walk } from './js-ast.js';
@@ -159,7 +159,7 @@ function jsPolicies(text, file, json) {
                     ? (value.properties.find((property) => property.type === 'ObjectProperty' && keyName(property) === 'directives')?.value ?? value) : value;
                 const policy = resolvePolicy(directives, ast);
                 // `csp` is a common key for other things; it counts only when it spells a policy.
-                if (name !== 'csp' || policy !== null)
+                if (name !== 'csp' || (policy !== null && DIRECTIVE.test(policy)))
                     found.push({ offset: node.start, policy, reportOnly: name.endsWith('report-only') });
                 seen.add(node.value);
             }
@@ -203,8 +203,9 @@ function resolvePolicy(node, ast, depth = 0) {
         && ['replace', 'replaceAll', 'trim'].includes(current.callee.property.name)) {
         return resolvePolicy(current.callee.object, ast, depth + 1);
     }
-    const policy = policyFromNode(current);
-    return policy !== null && DIRECTIVE.test(policy) ? policy : null;
+    // A header's value is its policy whatever it says (`frame-ancestors 'none'` restricts nothing the tag does); a computed
+    // value init cannot read stays null.
+    return policyFromNode(current);
 }
 /** helmet()'s default policy (helmet 5–8), which applies when its options leave contentSecurityPolicy alone. */
 const HELMET_DEFAULT = "default-src 'self'; base-uri 'self'; font-src 'self' https: data:; form-action 'self'; frame-ancestors 'self';"
@@ -298,7 +299,7 @@ export function findCsp(repoRoot, appDir, nextLoader, origins) {
         if (!MARKER.test(text))
             continue;
         const extension = extname(file);
-        const where = toPosix(file.slice(repoRoot.length + 1));
+        const where = toPosix(relative(repoRoot, file));
         let policies;
         if (['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx'].includes(extension))
             policies = jsPolicies(text, file, false);
@@ -327,5 +328,5 @@ export function findCsp(repoRoot, appDir, nextLoader, origins) {
             });
         }
     }
-    return { findings, looked: `${toPosix(appDir.slice(repoRoot.length + 1)) || '.'} (headers config, middleware, meta tags, framework CSP options, server configs)` };
+    return { findings, looked: `${toPosix(relative(repoRoot, appDir)) || '.'} (headers config, middleware, meta tags, framework CSP options, server configs)` };
 }

package/dist/capture/url-rewrites.js

@@ -0,0 +1,232 @@
+/**
+ * URL rewrites (CAPTURE-V1 rule 4). The tag matches a page's URL against the manifest's routes, so a route's rule must say
+ * which URLs show it. A middleware or proxy that rewrites (Rallly's proxy turns every /x into /<locale>/x) or a config
+ * rewrite into a page makes the URL and the route's path differ in ways only the app's code says. Init reads that code
+ * only where it can read it exactly (a middleware that rewrites nothing and calls nothing it cannot see into, or
+ * next-intl's middleware with a literal routing config); for anything else it never guesses: it asks the coding agent's
+ * user (who can read that code) for one answer, recorded in .haystack/capture.json:
+ *
+ *   none                     rewrites never make a page's URL show another page
+ *   hidden-segment:<name>    the middleware or proxy adds the leading dynamic segment [<name>] to every page path, so
+ *                            URLs never contain it (the manifest drops that segment from the routes under it)
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { keyName, literalValue, parseFile, pathOf, readPathAliases, resolveImport, unwrapTs, UNREADABLE, walk } from './js-ast.js';
+import { isFile } from './adapters/files.js';
+import { repoPath, resolveVersion } from './project.js';
+export function parseUrlRewrites(raw) {
+    const value = raw.trim();
+    if (value === 'none')
+        return { kind: 'none' };
+    const hidden = /^hidden-segment:([A-Za-z0-9_-]+)$/.exec(value);
+    if (hidden)
+        return { kind: 'hidden-segment', name: hidden[1] };
+    throw new Error(`--url-rewrites ${raw} is not an answer: use none, or hidden-segment:<name> for a leading [<name>] segment the app's middleware or proxy adds to every page path.`);
+}
+export const URL_REWRITES_QUESTION = 'Does it make a page\'s URL show another page? Ask your user (or read that code), then run `haystack init` again with'
+    + ' `--url-rewrites none` when its rewrites never do, or `--url-rewrites hidden-segment:<name>` when it adds a leading [<name>] segment to every'
+    + ' page path (so URLs never contain it).';
+const MIDDLEWARE_FILES = ['middleware', 'proxy'].flatMap(name => ['ts', 'js', 'mjs', 'mts', 'cts', 'cjs', 'tsx', 'jsx'].map(extension => `${name}.${extension}`));
+const INTL_MIDDLEWARE = 'next-intl/middleware';
+const INTL_ROUTING = 'next-intl/routing';
+/** next/server and the rest of Next's own modules: what they return init knows (NextResponse.rewrite is caught by name). */
+function nextModule(source) {
+    return source === 'next' || source.startsWith('next/');
+}
+/** The identifier a call's callee starts from (`a.b.c()` → a), or null (a call on a call's result, `(…)()`). */
+function calleeRoot(callee) {
+    let current = unwrapTs(callee);
+    while (current.type === 'MemberExpression' || current.type === 'OptionalMemberExpression')
+        current = unwrapTs(current.object);
+    return current.type === 'Identifier' ? current : null;
+}
+/** The value a routing config names: an object literal, a top-level const bound to one or to defineRouting({...}), or
+ * the same exported from a local module; null when it is not literally there. */
+function routingObject(node, ast, file, ctx, depth = 0) {
+    const current = unwrapTs(node);
+    if (depth > 4)
+        return null;
+    if (current.type === 'ObjectExpression')
+        return { value: current, ast };
+    if (current.type === 'CallExpression' && current.arguments.length === 1) {
+        const root = calleeRoot(current.callee);
+        const source = root ? importOf(ast, root.name) : null;
+        if (source?.module === INTL_ROUTING && source.imported === 'defineRouting')
+            return routingObject(current.arguments[0], ast, file, ctx, depth + 1);
+        return null;
+    }
+    if (current.type !== 'Identifier')
+        return null;
+    for (const statement of ast.program.body) {
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+        if (declaration?.type !== 'VariableDeclaration')
+            continue;
+        for (const declarator of declaration.declarations) {
+            if (declarator.id.type === 'Identifier' && declarator.id.name === current.name && declarator.init) {
+                return routingObject(declarator.init, ast, file, ctx, depth + 1);
+            }
+        }
+    }
+    const imported = importOf(ast, current.name);
+    if (!imported)
+        return null;
+    const target = resolveImport(file, imported.module, readPathAliases(ctx.appDir));
+    if (!target)
+        return null;
+    const targetAst = parseFile(readFileSync(target, 'utf8'), target);
+    if (!targetAst)
+        return null;
+    const exported = exportedExpression(targetAst, imported.imported);
+    return exported ? routingObject(exported, targetAst, target, ctx, depth + 1) : null;
+}
+function importOf(ast, local) {
+    for (const statement of ast.program.body) {
+        if (statement.type !== 'ImportDeclaration')
+            continue;
+        for (const specifier of statement.specifiers) {
+            if (specifier.local.name !== local)
+                continue;
+            const imported = specifier.type === 'ImportDefaultSpecifier' ? 'default'
+                : specifier.type === 'ImportNamespaceSpecifier' ? '*' : specifier.imported.name ?? specifier.imported.value;
+            return { module: statement.source.value, imported };
+        }
+    }
+    return null;
+}
+/** The expression a module exports under `name` ('default' for its default export), or null. */
+function exportedExpression(ast, name) {
+    for (const statement of ast.program.body) {
+        if (name === 'default' && statement.type === 'ExportDefaultDeclaration')
+            return statement.declaration;
+        if (statement.type !== 'ExportNamedDeclaration' || statement.source)
+            continue;
+        for (const declarator of statement.declaration?.type === 'VariableDeclaration' ? statement.declaration.declarations : []) {
+            if (declarator.id.type === 'Identifier' && declarator.id.name === name)
+                return declarator.init;
+        }
+        for (const specifier of statement.specifiers ?? []) {
+            if ((specifier.exported?.name ?? specifier.exported?.value) === name)
+                return specifier.local;
+        }
+    }
+    return null;
+}
+/** next-intl's routing, read exactly, or why it cannot be. */
+function intlRouting(config, ast, file, ctx, where) {
+    const unknown = (why) => ({ kind: 'unknown', why: `${where} uses next-intl's middleware, ${why}` });
+    const found = config ? routingObject(config, ast, file, ctx) : null;
+    if (!found)
+        return unknown('whose routing config init cannot read literally');
+    const value = literalValue(found.value, found.ast);
+    if (value === UNREADABLE || typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return unknown('whose routing config is not literal');
+    }
+    const routing = value;
+    if (routing.pathnames !== undefined)
+        return unknown('whose localized pathnames make a URL show a page under another path');
+    if (routing.domains !== undefined)
+        return unknown('whose domains decide the locale by host');
+    const locales = Array.isArray(routing.locales) && routing.locales.every(locale => typeof locale === 'string') ? routing.locales : null;
+    const defaultLocale = typeof routing.defaultLocale === 'string' ? routing.defaultLocale : null;
+    if (!locales || !defaultLocale)
+        return unknown('whose locales or defaultLocale are not a literal list and string');
+    let mode;
+    let prefixes = {};
+    const prefix = routing.localePrefix;
+    if (prefix === undefined) {
+        // next-intl 3 made `always` the default; 2 had `as-needed`.
+        const version = resolveVersion(ctx, 'next-intl');
+        if (!version || version.major === null)
+            return unknown('whose default localePrefix depends on a next-intl version init cannot resolve');
+        mode = version.major >= 3 ? 'always' : 'as-needed';
+    }
+    else if (typeof prefix === 'string') {
+        mode = prefix;
+    }
+    else if (prefix && typeof prefix === 'object' && !Array.isArray(prefix)) {
+        mode = prefix.mode;
+        if (prefix.prefixes !== undefined) {
+            const given = prefix.prefixes;
+            if (!given || typeof given !== 'object' || Array.isArray(given) || !Object.values(given).every(item => typeof item === 'string' && item.startsWith('/'))) {
+                return unknown('whose localePrefix.prefixes are not literal paths');
+            }
+            prefixes = given;
+        }
+    }
+    if (mode !== 'always' && mode !== 'as-needed' && mode !== 'never')
+        return unknown(`whose localePrefix mode (${JSON.stringify(mode)}) init does not know`);
+    return { kind: 'locale-prefix', where, mode, locales, defaultLocale, prefixes };
+}
+/** One middleware or proxy file, read. */
+function readMiddleware(ctx, file) {
+    const where = repoPath(ctx, file);
+    const ast = parseFile(readFileSync(file, 'utf8'), file);
+    if (!ast)
+        return { kind: 'unknown', why: `${where} (which init cannot parse)` };
+    const program = pathOf(ast, ast.program);
+    if (!program)
+        return { kind: 'unknown', why: `${where} (whose names init cannot resolve)` };
+    const reasons = [];
+    walk(ast.program, node => {
+        if (node.type === 'ExportAllDeclaration' || (node.type === 'ExportNamedDeclaration' && node.source)) {
+            reasons.push(`re-exports from ${node.source.value}`);
+        }
+        if (node.type === 'StringLiteral' && node.value.toLowerCase() === 'x-middleware-rewrite')
+            reasons.push('sets the x-middleware-rewrite header');
+        if ((node.type === 'CallExpression' || node.type === 'OptionalCallExpression') && node.callee.type === 'MemberExpression' && !node.callee.computed
+            && node.callee.property.name === 'rewrite')
+            reasons.push('calls rewrite()');
+        if (node.type === 'ObjectProperty' && keyName(node) === 'rewrite')
+            reasons.push('passes a rewrite');
+        if (node.type === 'ImportExpression' || (node.type === 'CallExpression' && (node.callee.type === 'Import'
+            || (node.callee.type === 'Identifier' && node.callee.name === 'require'))))
+            reasons.push('loads a module at runtime');
+    });
+    // Every value imported from outside Next is code init cannot see into, wherever it is used (called, passed to a local
+    // helper that calls it, exported as the middleware), except next-intl's createMiddleware and the routing it is given,
+    // which init reads.
+    const intlCalls = [];
+    for (const [local, binding] of Object.entries(program.scope.bindings)) {
+        const declaration = binding.path.parentPath?.node;
+        if (binding.kind !== 'module' || declaration?.type !== 'ImportDeclaration' || declaration.importKind === 'type'
+            || binding.path.node.importKind === 'type' || nextModule(declaration.source.value))
+            continue;
+        const factory = declaration.source.value === INTL_MIDDLEWARE && binding.path.node.type === 'ImportDefaultSpecifier';
+        for (const reference of binding.referencePaths) {
+            const parent = reference.parentPath?.node;
+            if (factory && parent?.type === 'CallExpression' && parent.callee === reference.node) {
+                intlCalls.push(parent);
+                continue;
+            }
+            const factoryArgument = parent?.type === 'CallExpression' && parent.arguments[0] === reference.node && parent.callee.type === 'Identifier'
+                && program.scope.getBinding(parent.callee.name)?.path.parentPath?.node.source?.value === INTL_MIDDLEWARE;
+            if (factoryArgument)
+                continue;
+            reasons.push(`uses ${local} from ${declaration.source.value}`);
+            break;
+        }
+    }
+    if (reasons.length > 0)
+        return { kind: 'unknown', why: `${where}, which ${reasons[0]} (init cannot read what that does to page paths)` };
+    if (intlCalls.length === 0)
+        return { kind: 'none' };
+    // next-intl: every createMiddleware call must read as the same routing.
+    const readings = intlCalls.map(call => intlRouting(call.arguments[0], ast, file, ctx, where));
+    const first = readings[0];
+    if (first.kind !== 'locale-prefix')
+        return first;
+    return readings.every(reading => JSON.stringify(reading) === JSON.stringify(first)) ? first
+        : { kind: 'unknown', why: `${where}, which calls next-intl's createMiddleware with several routing configs` };
+}
+/** What the app's middleware or proxy does to page paths (the first one found, as Next loads one). Needs loadBabel(). */
+export function middlewareRewrites(ctx) {
+    for (const dir of [ctx.appDir, join(ctx.appDir, 'src')]) {
+        for (const name of MIDDLEWARE_FILES) {
+            const file = join(dir, name);
+            if (isFile(file))
+                return readMiddleware(ctx, file);
+        }
+    }
+    return { kind: 'none' };
+}

package/dist/capture-step.js

@@ -42,6 +42,9 @@ try {
     if (written) {
         const files = Array.isArray(result.files) ? result.files.join(', ') : '';
         console.log(`Haystack route manifest ${String(result.release)}: ${files}`);
+        // What the person must still do for it to be reachable (a Next.js basePath): said on every build until done.
+        for (const note of Array.isArray(result.notes) ? result.notes : [])
+            console.warn(`haystack capture manifest: ${String(note)}.`);
     }
 }
 catch { /* the command did not answer: no manifest was written */ }

package/dist/commands/capture-manifest.js

@@ -5,13 +5,13 @@
  * current.json. No credential is involved: whoever deploys the app publishes its manifest.
  *
  * It runs inside the customer's build (the package script init extends, or the Rails rake file), from the CLI the app pins
- * as an exact devDependency. It never fails that build (rule 13): whatever goes wrong, it prints one warning line and exits
+ * as an exact production dependency. It never fails that build (rule 13): whatever goes wrong, it prints one warning line and exits
  * 0, because a missing manifest only stops the tag on this release (rule 13a: no manifest, no work). It needs no git
  * checkout: repository paths come from the app path init recorded.
  */
 import chalk from 'chalk';
 import { relative, resolve, sep } from 'node:path';
-import { detectApp } from '../capture/adapters/index.js';
+import { ADAPTER_IDS, detectApp, detectWith } from '../capture/adapters/index.js';
 import { isManual } from '../capture/adapters/types.js';
 import { CAPTURE_CONFIG_PATH, readCaptureConfig } from '../capture/app-config.js';
 import { loadBabel } from '../capture/js-ast.js';
@@ -44,35 +44,43 @@ async function publish(options, locations) {
     if (!config)
         throw new Error(`${appDir} has no ${CAPTURE_CONFIG_PATH}: run \`haystack init\` in the repository to set capture up.`);
     locations.push(...config.publish.map(dir => resolve(appDir, dir)));
-    if (config.adapter === null)
-        throw new Error(`${CAPTURE_CONFIG_PATH} names no framework adapter: init left this app's manifest to a manual step.`);
+    if (options.adapter !== undefined && !ADAPTER_IDS.includes(options.adapter)) {
+        throw new Error(`--adapter ${options.adapter} is not one of ${ADAPTER_IDS.join(', ')}`);
+    }
+    const adapter = (options.adapter ?? config.adapter);
+    if (adapter === null)
+        throw new Error(`${CAPTURE_CONFIG_PATH} names no framework adapter: run it with --adapter <${ADAPTER_IDS.join('|')}>`);
     // The checkout's root when the app sits at its recorded path; else (a build that sees only the app) the app itself.
     const suffix = config.app === '.' ? '' : config.app.split('/').join(sep);
     const repoRoot = suffix !== '' && appDir.endsWith(`${sep}${suffix}`) ? appDir.slice(0, -suffix.length - 1) : appDir;
     await loadBabel();
     const ctx = appContext(repoRoot, appDir, config.app);
-    const detected = await detectApp(ctx);
-    if (!detected || detected.id !== config.adapter) {
-        throw new Error(`${CAPTURE_CONFIG_PATH} was written for ${config.adapter}, and this app is now ${detected?.label ?? 'no framework init recognizes'}; run \`haystack init\` again.`);
-    }
-    if (!isManual(detected.publishDirs))
-        locations.push(...detected.publishDirs.map(dir => resolve(appDir, dir)).filter(dir => !locations.includes(dir)));
-    if (detected.blocked)
-        throw new Error(`${detected.label}: ${detected.blocked}.`);
-    const routes = exactRoutes(await detected.routes({ railsRoutes: options.railsRoutes ? resolve(options.railsRoutes) : undefined }));
-    if (isManual(routes))
-        throw new Error(routes.manual);
+    const detected = await detectWith(ctx, adapter);
+    if (!detected)
+        throw new Error(`the ${adapter} adapter does not recognize ${appDir} (${(await detectApp(ctx))?.label ?? 'no framework init recognizes'}); run \`haystack init\` again`);
+    // Checked on every build, so once the user removes the cause the next build publishes, with nothing to rerun.
+    if (detected.manifestBlocked)
+        throw new Error(`${detected.label}: ${detected.manifestBlocked}`);
     if (isManual(detected.publishDirs))
         throw new Error(detected.publishDirs.manual);
+    const publishDirs = [...detected.publishDirs, ...detected.buildPublishDirs()].map(dir => resolve(appDir, dir));
+    locations.push(...publishDirs.filter(dir => !locations.includes(dir)));
+    const routes = exactRoutes(await detected.routes({ railsRoutes: options.railsRoutes ? resolve(options.railsRoutes) : undefined,
+        urlRewrites: config.urlRewrites ?? null }));
+    if (isManual(routes))
+        throw new Error(routes.manual);
     const manifest = buildManifest(config, detected.manifestAdapter, routes, detected.chunks());
-    const written = writeManifest(detected.publishDirs.map(dir => resolve(appDir, dir)), manifest);
+    const written = writeManifest(publishDirs, manifest);
+    const notes = detected.buildNotes();
     if (options.json) {
         process.stdout.write(`${JSON.stringify({ written: true, release: manifest.release, routes: manifest.routes.length, chunks: manifest.chunks.length,
-            files: written.map(file => relative(appDir, file)) }, null, 2)}\n`);
+            files: written.map(file => relative(appDir, file)), notes }, null, 2)}\n`);
         return;
     }
     const count = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
     console.log(chalk.green(`Haystack route manifest ${manifest.release}: ${count(manifest.routes.length, 'route')}, ${count(manifest.chunks.length, 'chunk')} (${detected.label})`));
     for (const file of written)
         console.log(chalk.dim(`  ${relative(appDir, file)}`));
+    for (const note of notes)
+        console.warn(chalk.yellow(`haystack capture manifest: ${note}.`));
 }

package/dist/commands/init-capture.js

@@ -31,8 +31,9 @@ import { findCsp } from '../capture/csp.js';
 import { applyEdits, keyName, loadBabel, parseJsonLike } from '../capture/js-ast.js';
 import { buildManifest, exactRoutes, manifestDocument, MANIFEST_DIR } from '../capture/manifest.js';
 import { appContext } from '../capture/project.js';
+import { parseUrlRewrites, URL_REWRITES_QUESTION } from '../capture/url-rewrites.js';
 import { loadCaptureScript } from '../capture/script-release.js';
-import { htmlTags, STATIC_SUBDIR } from '../capture/tag.js';
+import { STATIC_SUBDIR } from '../capture/tag.js';
 import { CAPTURE_ORIGIN, CAPTURE_VERSION } from './capture-contract.js';
 import { HaystackApiError } from '../utils/haystack-api.js';
 import { lineDiff } from './init.js';
@@ -50,9 +51,10 @@ const COMPOSABLE_SCRIPT = /^[A-Za-z0-9_./=:@\s&-]+$/;
 const STAGED_DIR = `.haystack/${STATIC_SUBDIR}`;
 /** The answers in effect: the flags, else the ones init recorded in .haystack/capture.json (rule 8b: the user's answers,
  * never inferred, so a rerun that only updates the script needs none). */
-export function captureAnswers(appDir, origins, consent) {
+export function captureAnswers(appDir, origins, consent, urlRewrites) {
     const recorded = readCaptureConfig(appDir);
-    return { origins: origins.length > 0 ? origins : recorded?.origins ?? [], consent: consent ?? recorded?.consent };
+    return { origins: origins.length > 0 ? origins : recorded?.origins ?? [], consent: consent ?? recorded?.consent,
+        urlRewrites: urlRewrites ?? recorded?.urlRewrites ?? undefined };
 }
 function readText(path) {
     try {
@@ -126,6 +128,9 @@ function scriptFiles(dir) {
         return [];
     }
 }
+function formatUrlRewrites(rewrites) {
+    return rewrites.kind === 'none' ? 'none' : `hidden-segment:${rewrites.name}`;
+}
 function manifestCommand(appPath) {
     return `haystack capture manifest --app ${appPath}`;
 }
@@ -144,6 +149,7 @@ export async function planCapture(input) {
     if (input.answers.consent === undefined)
         throw new Error('planCapture needs the consent answer.');
     const consent = parseConsentChoice(input.answers.consent);
+    const urlRewrites = input.answers.urlRewrites === undefined ? null : formatUrlRewrites(parseUrlRewrites(input.answers.urlRewrites));
     const plan = { changes: [], packageText: null, needsCli: false, registration: null, notices: [], part: part([]) };
     if (input.registration && 'failed' in input.registration) {
         plan.part = part([`Run \`haystack init\` again: registering the app for capture failed (${input.registration.failed}).`]);
@@ -182,18 +188,36 @@ export async function planCapture(input) {
         key: tags.key,
         repositoryId: identity?.repositoryId ?? ID_PLACEHOLDER,
         applicationId: identity?.applicationId ?? ID_PLACEHOLDER,
-        adapter: detected && !detected.blocked ? detected.id : null,
+        // The adapter init recognized, whatever it left manual: the manifest command uses it once the cause is fixed.
+        adapter: detected ? detected.id : null,
         app: ctx.appPath,
         origins,
         consent: formatConsentChoice(consent),
         // Where a build step publishes (none for a static site, whose manifest init writes and the repository keeps).
-        publish: detected && !detected.blocked && !isManual(detected.publishDirs) && !isManual(detected.build)
-            && detected.build.kind !== 'init-writes' ? detected.publishDirs : [],
+        publish: detected && !isManual(detected.publishDirs) && !isManual(detected.build) && detected.build.kind !== 'init-writes'
+            ? detected.publishDirs : [],
+        urlRewrites,
     };
     planner.text(captureConfigFile(appDir), formatCaptureConfig(config), 'The app\'s capture identity, committed for the build step that publishes its route manifest (CAPTURE-V1 rule 8b).');
     const consentStep = manualConsentStep(consent);
-    const automatic = detected !== null && detected.blocked === null;
-    const staticDir = automatic && typeof detected.staticDir === 'string' ? detected.staticDir : null;
+    if (!detected) {
+        plan.part = { status: 'unsupported', why: `init recognized no web framework at ${ctx.appPath} (it looked for package.json, Gemfile,`
+                + ' manage.py and index.html there), and the tag records nothing without the route manifest only a recognized framework\'s routes'
+                + ' give; run `haystack init --app <dir>` with the app\'s directory' };
+        plan.changes = planner.changes;
+        return plan;
+    }
+    // A manifest that cannot be made exactly (a base path, a config init cannot read) leaves nothing worth placing: a tag
+    // without a manifest records nothing. Two steps that work: remove the cause, run init again (the recorded answers carry
+    // over, and the manifest command checks the cause on every build).
+    if (detected.manifestBlocked) {
+        steps.push(`Remove what stops ${detected.label}'s route manifest: ${detected.manifestBlocked} (init looked at ${detected.looked.join(', ')}).`);
+        steps.push('Then run `haystack init` again: it places the tag, the files and the build step that publishes the manifest itself.');
+        plan.changes = planner.changes;
+        plan.part = part(steps);
+        return plan;
+    }
+    const staticDir = typeof detected.staticDir === 'string' ? detected.staticDir : null;
     // The files: in the app's static output, or staged for a manual step.
     const filesDir = staticDir === null ? join(appDir, STAGED_DIR) : join(appDir, staticDir, STATIC_SUBDIR);
     const wanted = new Set([script.file, ...(consentFile ? [consentFile.file] : [])]);
@@ -205,24 +229,8 @@ export async function planCapture(input) {
         if (!wanted.has(old))
             planner.remove(join(filesDir, old), 'An earlier capture file, replaced by this version.');
     const servedAt = `/${STATIC_SUBDIR}/`;
-    if (!automatic) {
-        const why = detected ? `${detected.label}: ${detected.blocked}` : `init recognized no framework at ${ctx.appPath}`;
-        const looked = detected?.looked.join(', ') ?? `${ctx.appPath} (package.json, Gemfile, manage.py, index.html)`;
-        steps.push(`Add the tag yourself (${why}; init looked at ${looked}):\n${(detected ? detected.manualTag(tags) : ['Inside <head> of every page:', ...htmlTags(tags)]).map(line => `  ${line}`).join('\n')}`);
-        steps.push(`Serve the files init staged in ${posix.join(ctx.appPath, STAGED_DIR)}/ at ${servedAt} on each production origin.`);
-        steps.push(`Publish the route manifest (CAPTURE-V1 rule 4) after each build at /${MANIFEST_DIR}/current.json and`
-            + ` /${MANIFEST_DIR}/<release>.json on each production origin; until one is published the tag records nothing.`
-            + ` \`${manifestCommand(ctx.appPath)}\` generates it only for an app init sets up itself: once the reason above is gone,`
-            + ' run `haystack init` again and it adds that build step.');
-        steps.push(`If production sends a Content-Security-Policy, it needs: ${cspFallbackLine()}.`);
-        if (consentStep)
-            steps.push(consentStep);
-        plan.changes = planner.changes;
-        plan.part = part(steps);
-        return plan;
-    }
     // The tag.
-    const integration = await detected.integrate(tags);
+    const integration = detected.blocked ? { manual: detected.blocked } : await detected.integrate(tags);
     if (isManual(integration)) {
         steps.push(`Add the tag yourself (${integration.manual}; init looked at ${detected.looked.join(', ')}):\n${detected.manualTag(tags).map(line => `  ${line}`).join('\n')}`);
     }
@@ -234,8 +242,17 @@ export async function planCapture(input) {
         steps.push(`Serve ${posix.join(ctx.appPath, STAGED_DIR)} at ${servedAt}: ${detected.staticDir.manual}.`);
     // The build step and where the manifest goes.
     await planBuild(plan, planner, steps, ctx, detected, config);
-    // Routes now, so a router init cannot read is a step today rather than a manifest missing after the next build.
-    if (!isManual(detected.build) && detected.build.kind !== 'rake') {
+    if (detected.publishNote)
+        plan.notices.push(`Capture: ${detected.publishNote}`);
+    // A middleware or proxy that may rewrite page URLs: the routes are exact only with the user's answer.
+    if (detected.rewriting && urlRewrites === null)
+        steps.push(`Answer one question about URL rewrites: ${detected.rewriting}. ${URL_REWRITES_QUESTION}`);
+    // Routes now, so a router init cannot read is a step today rather than a manifest missing after the next build; an
+    // adapter whose routes come from the build reads them there.
+    if (detected.fromBuild) {
+        plan.notices.push(`Capture: the routes come from each production build (${detected.label}), read after it by the build step.`);
+    }
+    else if (!isManual(detected.build) && detected.build.kind !== 'rake') {
         const routes = exactRoutes(await detected.routes({}));
         if (isManual(routes))
             steps.push(`Make the routes readable or publish the manifest yourself: ${routes.manual}.`);

package/dist/commands/init-telemetry.js

@@ -841,7 +841,7 @@ export async function planTelemetry(gitRoot, repository, options) {
     const manifest = join(appDir, 'package.json');
     // CONNECT(lane D1): browser capture (init-capture.ts) plans with the answers in effect (flags, else the ones init recorded
     // for this app); a missing answer is a question, never a guess.
-    const answers = captureAnswers(appDir, options.origins, options.consent);
+    const answers = captureAnswers(appDir, options.origins, options.consent, options.urlRewrites);
     const questions = captureQuestions(answers.origins, answers.consent);
     const capture = questions.length > 0 ? null
         : await planCapture({ gitRoot, appDir, repository, answers, registration: options.registration });
@@ -940,19 +940,36 @@ function dbProfile(repository, onboarding, notes) {
                         + '`haystack db profile upload --help` says how a profile names the one it describes.'] : []),
         ] };
 }
+function serverPartOf(plan) {
+    return plan.server.status === 'unsupported' ? { status: 'unsupported', why: plan.server.why }
+        : plan.server.status === 'manual' ? { status: 'manual', steps: plan.server.steps, received: null } : { status: 'installed', received: null };
+}
+const WAITING_STEP = 'Telemetry waits for answers only your user can give: ask what the `steps` of each `manual` part say, then run `haystack init` '
+    + 'again with them.';
+/** Rule 8(e) before anything is changed (a preview without --yes, or no login yet): the report the apply gives, with
+ * `received` null (checking it needs Haystack), so the coding agent can show its user what telemetry will do; with the steps that need
+ * nothing from Haystack (the token and environment steps follow with --yes). */
+export function previewTelemetry(plan, repository, notes) {
+    const steps = [];
+    if (plan.app === null || plan.capture.status === 'manual')
+        steps.push(WAITING_STEP);
+    if (plan.app !== null && plan.server.status !== 'unsupported') {
+        steps.push(`With --yes, init then says how production gets its telemetry token (\`haystack telemetry token --repo ${repository}\`, run by your`
+            + ' user in their own terminal) and which variables production\'s server environment needs.');
+    }
+    const profile = dbProfile(repository, null, notes);
+    return { telemetry: { capture: plan.capture, server: serverPartOf(plan), dbProfileCommand: profile?.command ?? null }, steps };
+}
 /** Rule 8(e): the report, and what the person does for telemetry to arrive (the token, production's environment, the start,
  * the deploy) with the off switches (rule 13c). `onboarding` and `notes` feed the data profile. */
 export async function telemetryReport(plan, context) {
     const { repository, token } = context;
     const steps = [];
-    const serverPart = plan.server.status === 'unsupported' ? { status: 'unsupported', why: plan.server.why }
-        : plan.server.status === 'manual' ? { status: 'manual', steps: plan.server.steps, received: null } : { status: 'installed', received: null };
+    const serverPart = serverPartOf(plan);
     let server = serverPart;
     // Answers only the user can give come first: until then the rest of telemetry waits (rule 8: init never guesses).
-    if (plan.app === null || plan.capture.status === 'manual') {
-        steps.push('Telemetry waits for answers only your user can give: ask what the `steps` of each `manual` part say, then run `haystack init` '
-            + 'again with them.');
-    }
+    if (plan.app === null || plan.capture.status === 'manual')
+        steps.push(WAITING_STEP);
     if (plan.app !== null && plan.server.status !== 'unsupported') {
         const status = await readTelemetryServerStatus(repository, token);
         server = withReceived(serverPart, status.newestFlush === null ? null : received(status.newestFlush.storedAt, status.newestFlush.buildId));