@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/capture/adapters/nuxt.js

@@ -0,0 +1,199 @@
+/**
+ * Nuxt 3–4 (CAPTURE-V1 rule 8b).
+ *
+ * Tag: an entry of nuxt.config's app.head.script ({ src, integrity, 'data-key', async: true }), which Nuxt renders into
+ * every page's <head>; init creates app, head or script where missing and leaves a config it cannot read to a manual
+ * step. Static output: public/ (Nuxt 4: at the root; Nuxt 3: under srcDir). Routes: the pages directory (index for the
+ * parent's path, [id], [[id]], [...slug], (group) directories); an app without pages/ is one page, `/`. Nitro presets
+ * reshape the output inside `nuxt build`, so the build step publishes the manifest into public/ BEFORE the build,
+ * without chunks. app.baseURL other than / is a manual step.
+ */
+import { readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { applyEdits, configObject, indentUnit, keyName, lineIndent, parseFile, startsLine, unwrapTs } from '../js-ast.js';
+import { repoPath, resolveVersion, appFile } from '../project.js';
+import { paramName, ruleFor } from '../route-pattern.js';
+import { nuxtScriptEntries, ourScriptKind } from '../tag.js';
+import { configFile, configValue, filesUnder, isDirectory, isFile } from './files.js';
+const PAGE_EXTENSIONS = ['.vue', '.tsx', '.jsx', '.ts', '.js', '.mjs'];
+export function nuxtSegment(name) {
+    if (/^\(.+\)$/.test(name))
+        return null;
+    const optional = /^\[\[([^\]]+)\]\]$/.exec(name);
+    if (optional)
+        return { kind: 'param', name: paramName(optional[1]), optional: true };
+    const rest = /^\[\.\.\.([^\]]+)\]$/.exec(name);
+    if (rest)
+        return { kind: 'splat', name: paramName(rest[1]), optional: true };
+    const param = /^\[([^\]]+)\]$/.exec(name);
+    if (param)
+        return { kind: 'param', name: paramName(param[1]), optional: false };
+    if (name.includes('['))
+        return { kind: 'param', name: paramName(name), optional: false, inexact: `a segment mixing text and a parameter (${name})` };
+    return { kind: 'literal', value: name };
+}
+function property(object, name) {
+    return object.properties.find((candidate) => candidate.type === 'ObjectProperty' && keyName(candidate) === name) ?? null;
+}
+/** Text that adds `text` as the first property of `object`. */
+function firstProperty(code, object, text, unit) {
+    if (object.properties.length === 0) {
+        const indent = lineIndent(code, object.start);
+        return { start: object.start, end: object.end, text: `{\n${indent}${unit}${text},\n${indent}}` };
+    }
+    const first = object.properties[0];
+    if (startsLine(code, first.start)) {
+        const lineStart = code.lastIndexOf('\n', first.start - 1) + 1;
+        return { start: lineStart, end: lineStart, text: `${lineIndent(code, first.start)}${text},\n` };
+    }
+    return { start: first.start, end: first.start, text: `${text}, ` };
+}
+function ourEntries(array) {
+    return array.elements.filter((element) => {
+        if (element?.type !== 'ObjectExpression')
+            return false;
+        const src = property(element, 'src')?.value;
+        return src?.type === 'StringLiteral' && ourScriptKind(src.value) !== null;
+    });
+}
+function configEdit(file, tags) {
+    const code = readFileSync(file, 'utf8');
+    const ast = parseFile(code, file);
+    if (!ast)
+        return { manual: `${file} does not parse` };
+    const config = configObject(ast);
+    if (!config)
+        return { manual: 'nuxt.config does not export a config object init can read' };
+    const unit = indentUnit(code);
+    const entries = nuxtScriptEntries(tags);
+    const array = `[${entries.join(', ')}]`;
+    let edits;
+    const app = property(config, 'app');
+    const head = app && unwrapTs(app.value).type === 'ObjectExpression' ? property(unwrapTs(app.value), 'head') : null;
+    const script = head && unwrapTs(head.value).type === 'ObjectExpression' ? property(unwrapTs(head.value), 'script') : null;
+    if (!app) {
+        edits = [firstProperty(code, config, `app: { head: { script: ${array} } }`, unit)];
+    }
+    else if (unwrapTs(app.value).type !== 'ObjectExpression') {
+        return { manual: 'nuxt.config\'s app is not an object literal' };
+    }
+    else if (!head) {
+        edits = [firstProperty(code, unwrapTs(app.value), `head: { script: ${array} }`, unit)];
+    }
+    else if (unwrapTs(head.value).type !== 'ObjectExpression') {
+        return { manual: 'nuxt.config\'s app.head is not an object literal' };
+    }
+    else if (!script) {
+        edits = [firstProperty(code, unwrapTs(head.value), `script: ${array}`, unit)];
+    }
+    else {
+        const list = unwrapTs(script.value);
+        if (list.type !== 'ArrayExpression')
+            return { manual: 'nuxt.config\'s app.head.script is not an array literal' };
+        const ours = ourEntries(list);
+        const current = ours.map(node => code.slice(node.start, node.end));
+        if (current.length === entries.length && current.every((text, index) => text === entries[index]))
+            return [{ target: file, content: code }];
+        if (ours.length > 0) {
+            edits = [{ start: ours[0].start, end: ours[0].end, text: entries.join(', ') },
+                ...ours.slice(1).map(node => {
+                    const after = code.slice(node.end).match(/^\s*,/);
+                    return { start: node.start, end: node.end + (after ? after[0].length : 0), text: '' };
+                })];
+        }
+        else {
+            const last = list.elements[list.elements.length - 1];
+            if (!last) {
+                edits = [{ start: list.start, end: list.end, text: array }];
+            }
+            else {
+                const between = code.slice(last.end, list.end - 1);
+                const comma = between.indexOf(',');
+                const separator = startsLine(code, last.start) ? `\n${lineIndent(code, last.start)}` : ' ';
+                edits = comma === -1
+                    ? [{ start: last.end, end: last.end, text: entries.map(entry => `,${separator}${entry}`).join('') }]
+                    : [{ start: last.end + comma + 1, end: last.end + comma + 1, text: entries.map(entry => `${separator}${entry},`).join('') }];
+            }
+        }
+    }
+    const next = applyEdits(code, edits);
+    const check = parseFile(next, file);
+    const checkConfig = check ? configObject(check) : null;
+    const checkApp = checkConfig ? property(checkConfig, 'app') : null;
+    const checkHead = checkApp ? property(unwrapTs(checkApp.value), 'head') : null;
+    const checkScript = checkHead ? property(unwrapTs(checkHead.value), 'script') : null;
+    const placed = checkScript ? ourEntries(unwrapTs(checkScript.value)).map(node => next.slice(node.start, node.end)) : [];
+    if (placed.length !== entries.length || placed.some((text, index) => text !== entries[index])) {
+        return { manual: 'the edit to nuxt.config did not leave exactly one tag' };
+    }
+    return [{ target: file, content: next }];
+}
+export async function detectNuxt(ctx) {
+    const version = resolveVersion(ctx, 'nuxt');
+    if (!version)
+        return null;
+    const config = configFile(ctx.appDir, ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs', 'nuxt.config.mts']);
+    const where = config.file ? repoPath(ctx, config.file) : appFile(ctx, 'nuxt.config.ts');
+    const blocked = [];
+    const compatibility = configValue(config, ['future', 'compatibilityVersion']);
+    const four = version.major === 4 || (compatibility.state === 'value' && compatibility.value === 4);
+    if (version.major !== 3 && version.major !== 4)
+        blocked.push(`init knows Nuxt 3–4, and this app's version is ${version.version} (${version.from})`);
+    const read = (path, fallback) => {
+        const value = configValue(config, path);
+        if (value.state === 'unreadable' || (value.state === 'value' && typeof value.value !== 'string')) {
+            blocked.push(`${where} sets ${path.join('.')} in a way init cannot read`);
+            return fallback;
+        }
+        return value.state === 'value' ? value.value : fallback;
+    };
+    const srcDir = read(['srcDir'], four ? 'app' : '.');
+    const pagesDir = read(['dir', 'pages'], 'pages');
+    const publicDir = posix.join(four ? '.' : srcDir, read(['dir', 'public'], 'public'));
+    const baseURL = read(['app', 'baseURL'], '/');
+    if (baseURL !== '/')
+        blocked.push(`${where} sets app.baseURL ${baseURL}: the route manifest must be published at the origin root, outside it`);
+    const pages = join(ctx.appDir, srcDir, pagesDir);
+    const scripts = ctx.pkg?.scripts ?? {};
+    const buildScript = typeof scripts.build === 'string' ? 'build' : typeof scripts.generate === 'string' ? 'generate' : null;
+    return {
+        id: 'nuxt',
+        label: `Nuxt ${version.version}`,
+        manifestAdapter: `nuxt@${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: [where, repoPath(ctx, pages)],
+        staticDir: publicDir,
+        integrate: async (tags) => (config.file ? configEdit(config.file, tags) : { manual: `${where} is missing` }),
+        manualTag: tags => [`In ${where}, under app.head.script:`, ...nuxtScriptEntries(tags)],
+        build: buildScript ? { kind: 'package-script', script: buildScript, phase: 'before' }
+            : { manual: `${appFile(ctx, 'package.json')} has no build or generate script to publish the route manifest before` },
+        async routes() {
+            if (!isDirectory(pages)) {
+                const app = ['app.vue'].map(name => join(ctx.appDir, srcDir, name)).find(isFile);
+                return [{ match: '/', source: repoPath(ctx, app ?? config.file) }];
+            }
+            const routes = [];
+            for (const file of filesUnder(pages)) {
+                const extension = PAGE_EXTENSIONS.find(candidate => file.endsWith(candidate));
+                if (!extension)
+                    continue;
+                const parts = file.slice(0, -extension.length).split('/');
+                const index = parts[parts.length - 1] === 'index';
+                if (index)
+                    parts.pop();
+                const segments = parts.map(nuxtSegment).filter((segment) => segment !== null);
+                routes.push({ ...ruleFor(segments), source: repoPath(ctx, join(pages, file)), rank: index ? 0 : 1 });
+            }
+            return routes;
+        },
+        chunks: () => [],
+        publishDirs: [publicDir],
+    };
+}

package/dist/capture/adapters/rails.js

@@ -0,0 +1,178 @@
+/**
+ * Rails 6–8 (CAPTURE-V1 rule 8b).
+ *
+ * Tag: an async script before </head> of the app's one HTML layout in app/views/layouts (ERB; mailer layouts are emails
+ * and never get it; several page layouts, or Haml/Slim, are a manual step). Static output: public/.
+ *
+ * Routes: Rails' own route set, which only Rails can evaluate, so the build step is a rake file that runs after
+ * assets:precompile (when the app is booted): it writes the GET routes Rails lists (path spec, controller, action) to
+ * tmp/ and runs `haystack capture manifest --rails-routes <file>` of the CLI package.json pins, never failing the build. Path specs become
+ * patterns: (.:format) is dropped, other optional groups make their segments optional, *glob is a splat. Each route's
+ * source is its controller file. Chunks: none declared.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { withHeadTags, scanHtml } from '../html.js';
+import { gemVersion, repoPath } from '../project.js';
+import { paramName, ruleFor } from '../route-pattern.js';
+import { htmlTags } from '../tag.js';
+import { filesUnder, isFile } from './files.js';
+export const RAKE_FILE = 'lib/tasks/haystack_capture.rake';
+/** The rake file: after assets:precompile, the app's GET routes into tmp/, then the manifest command of the CLI the app
+ * pins (node_modules/.bin, never npx). The command exits 0 whatever happens, and a missing CLI is one warning. */
+export const RAKE_FILE_CONTENT = `# Written by \`haystack init\` (CAPTURE-V1 rule 4). After assets:precompile, publishes this app's route manifest into
+# public/.well-known/haystack-capture/ from the routes Rails itself lists, with the @haystackeditor/cli package.json pins.
+# It never fails the build (rule 13): a manifest that cannot be made only means the tag records nothing on this release,
+# and the previous release's current.json is removed rather than shipped.
+if Rake::Task.task_defined?('assets:precompile')
+  Rake::Task['assets:precompile'].enhance do
+    current = Rails.root.join('public', '.well-known', 'haystack-capture', 'current.json')
+    begin
+      require 'json'
+      require 'fileutils'
+      step = Rails.root.join('node_modules', '.bin', 'haystack-capture-step')
+      if File.exist?(step)
+        routes = Rails.application.routes.routes.filter_map do |route|
+          verb = route.verb.to_s
+          next unless verb.empty? || verb.split('|').include?('GET')
+          next if route.respond_to?(:internal) && route.internal
+          controller = route.defaults[:controller]
+          next unless controller
+          { path: route.path.spec.to_s, controller: controller.to_s, action: route.defaults[:action].to_s }
+        end
+        file = Rails.root.join('tmp', 'haystack-capture-routes.json')
+        FileUtils.mkdir_p(File.dirname(file))
+        File.write(file, JSON.generate(routes))
+        # The step exits 0 whatever happens and removes current.json itself when no manifest was written.
+        system(step.to_s, '--rails-routes', file.to_s, chdir: Rails.root.to_s)
+      else
+        File.delete(current) if File.exist?(current)
+        warn('haystack capture manifest: @haystackeditor/cli is not installed (node_modules/.bin/haystack-capture-step); the build goes on without a route manifest.')
+      end
+    rescue StandardError => e
+      begin
+        File.delete(current) if File.exist?(current)
+      rescue StandardError
+        nil
+      end
+      warn("haystack capture manifest: #{e.class}; the build goes on without a route manifest.")
+    end
+  end
+end
+`;
+/** A Rails path spec (`/users/:id(.:format)`, `(/:locale)/posts/*rest`) as segments (an inexact one marked, route-pattern.ts
+ * ruleFor); null when its parentheses do not balance. */
+export function railsSegments(spec) {
+    const parts = [];
+    let depth = 0;
+    let text = '';
+    let startDepth = -1;
+    const flush = () => {
+        if (text !== '')
+            parts.push({ text, optional: startDepth > 0 });
+        text = '';
+        startDepth = -1;
+    };
+    for (const char of spec.split('(.:format)').join('')) {
+        if (char === '(') {
+            depth += 1;
+            continue;
+        }
+        if (char === ')') {
+            depth -= 1;
+            if (depth < 0)
+                return null;
+            continue;
+        }
+        if (char === '/') {
+            flush();
+            continue;
+        }
+        if (startDepth === -1)
+            startDepth = depth;
+        text += char;
+    }
+    if (depth !== 0)
+        return null;
+    flush();
+    const segments = parts.map(({ text: part, optional }) => {
+        if (/^\*[A-Za-z_][A-Za-z0-9_]*$/.test(part))
+            return { kind: 'splat', name: paramName(part.slice(1)), optional };
+        if (/^:[A-Za-z_][A-Za-z0-9_]*$/.test(part))
+            return { kind: 'param', name: paramName(part.slice(1)), optional };
+        // A segment mixing text and parameters (`:id-:slug`), or an optional literal, has no exact form in the pattern syntax.
+        if (part.includes(':') || part.includes('*') || optional) {
+            return { kind: 'param', name: paramName(part), optional, inexact: `${optional ? 'an optional segment' : 'a segment mixing text and parameters'} (${part})` };
+        }
+        return { kind: 'literal', value: part };
+    });
+    return segments;
+}
+function layouts(appDir) {
+    const dir = join(appDir, 'app', 'views', 'layouts');
+    const files = filesUnder(dir).filter(file => !file.split('/').pop()?.startsWith('mailer') && !file.startsWith('mailer'));
+    const pages = files.filter(file => /\.html\.erb$/.test(file) && scanHtml(readFileSync(join(dir, file), 'utf8')).heads.length > 0);
+    return { erb: pages.map(file => join(dir, file)), other: files.filter(file => /\.html\.(haml|slim)$/.test(file)).map(file => join(dir, file)) };
+}
+export async function detectRails(ctx) {
+    const gemfile = join(ctx.appDir, 'Gemfile');
+    if (!isFile(gemfile) || !isFile(join(ctx.appDir, 'config', 'routes.rb')))
+        return null;
+    if (!/^\s*gem\s+['"]rails['"]/m.test(readFileSync(gemfile, 'utf8')))
+        return null;
+    const version = gemVersion(ctx.appDir, 'rails') ?? gemVersion(ctx.appDir, 'railties');
+    const blocked = [];
+    if (!version || version.major === null || version.major < 6 || version.major > 8) {
+        blocked.push(`init knows Rails 6–8, and this app's version is ${version ? `${version.version} (Gemfile.lock)` : 'not in a Gemfile.lock'}`);
+    }
+    const found = layouts(ctx.appDir);
+    const layoutsPath = repoPath(ctx, join(ctx.appDir, 'app', 'views', 'layouts'));
+    return {
+        id: 'rails',
+        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) {
+            if (found.erb.length !== 1) {
+                const other = found.other.length > 0 ? ` (and ${found.other.map(file => repoPath(ctx, file)).join(', ')}, which init does not edit)` : '';
+                return { manual: `${layoutsPath} has ${found.erb.length} ERB page layouts with a <head>${other}, not one` };
+            }
+            const file = found.erb[0];
+            const edit = withHeadTags(readFileSync(file, 'utf8'), htmlTags(tags));
+            return 'manual' in edit ? { manual: `${repoPath(ctx, file)}: ${edit.manual}` } : [{ target: file, content: edit.content }];
+        },
+        manualTag: tags => [`In your page layout (${layoutsPath}/application.html.erb), inside <head>:`, ...htmlTags(tags)],
+        build: { kind: 'rake' },
+        async routes(inputs) {
+            if (!inputs.railsRoutes || !existsSync(inputs.railsRoutes)) {
+                return { manual: 'Rails routes come from the rake task after assets:precompile (--rails-routes); run the app\'s build' };
+            }
+            const listed = JSON.parse(readFileSync(inputs.railsRoutes, 'utf8'));
+            const routes = [];
+            for (const route of listed) {
+                if (typeof route.path !== 'string' || typeof route.controller !== 'string' || !/^[a-z0-9_/]+$/.test(route.controller))
+                    continue;
+                const segments = railsSegments(route.path);
+                // A controller outside app/controllers belongs to a gem or engine (Active Storage, Devise): its pages are not this
+                // repository's files, so they stay `unknown` rather than being joined to a file that did not define them.
+                const controller = join(ctx.appDir, 'app', 'controllers', `${route.controller}_controller.rb`);
+                if (!existsSync(controller))
+                    continue;
+                routes.push(segments ? { ...ruleFor(segments), source: repoPath(ctx, controller) }
+                    : { match: '/', source: repoPath(ctx, controller), inexact: `a path spec the pattern syntax cannot express (${route.path})` });
+            }
+            return routes;
+        },
+        chunks: () => [],
+        publishDirs: ['public'],
+    };
+}