@pikku/cli 0.12.91 → 0.12.92

package/dist/src/functions/commands/scenario-environment.js

@@ -0,0 +1,61 @@
+/**
+ * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ *
+ * The configured environment is the base; `--api-url`/`--app-url` override it
+ * for one invocation, which is what makes a suite runnable against a target
+ * that only exists at run time (a freshly provisioned sandbox) without writing
+ * a pikku.config.json per deployment.
+ */
+const LOCAL_HOSTNAMES = new Set([
+    'localhost',
+    '127.0.0.1',
+    '0.0.0.0',
+    '::1',
+    '[::1]',
+]);
+/**
+ * Absolute URLs only: the value is concatenated with paths (`${apiUrl}/rpc`)
+ * and parsed by the spawn path, so a relative one fails far from its cause.
+ */
+const assertAbsoluteUrl = (flag, value) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${flag} '${value}' is not a valid absolute URL — pass one including the scheme, e.g. ${flag} https://sandbox-a1b2.example.com/api`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`${flag} '${value}' must be an http(s) URL, not '${url.protocol.replace(':', '')}'.`);
+    }
+    return url;
+};
+/**
+ * Applied once, so actors, step env, the browser driver and the spawned server
+ * all see the same target. The environment is still looked up by name: the
+ * flags override fields on a configured environment, they do not invent one.
+ */
+export const resolveScenarioEnvironment = ({ environment, environments, apiUrl, appUrl, spawn = false, }) => {
+    const configured = environments[environment];
+    if (!configured) {
+        const known = Object.keys(environments);
+        throw new Error(`Unknown scenario environment '${environment}'. ` +
+            (known.length
+                ? `Configured environments: ${known.join(', ')}`
+                : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
+    }
+    const resolved = { ...configured };
+    if (apiUrl !== undefined) {
+        const url = assertAbsoluteUrl('--api-url', apiUrl);
+        if (spawn && !LOCAL_HOSTNAMES.has(url.hostname)) {
+            throw new Error(`--spawn starts a server on this machine, but --api-url points at '${url.hostname}'. ` +
+                `Drop --spawn to run against an already-serving target, or point --api-url at localhost.`);
+        }
+        resolved.apiUrl = apiUrl;
+    }
+    if (appUrl !== undefined) {
+        assertAbsoluteUrl('--app-url', appUrl);
+        resolved.appUrl = appUrl;
+    }
+    return resolved;
+};

package/dist/src/functions/commands/scenario.d.ts

@@ -10,6 +10,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    apiUrl?: string;
+    appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     environment: string;
     flows?: string;
@@ -21,6 +23,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    apiUrl?: string;
+    appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
     environment: string;
     flows?: string;
@@ -32,4 +36,6 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    apiUrl?: string;
+    appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/scenario.js

@@ -12,6 +12,7 @@ import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './sce
 import { resolveScenarioActors } from '../../utils/resolve-scenario-actors.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
 import { buildScenarioPlan } from './scenario-plan.js';
+import { resolveScenarioEnvironment } from './scenario-environment.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -83,16 +84,20 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
         const state = await getInspectorState(true, false, false, true);
-        const environments = config.scenarios?.environments ?? {};
-        const env = environments[environment];
-        if (!env) {
-            const known = Object.keys(environments);
-            throw new Error(`Unknown scenario environment '${environment}'. ` +
-                (known.length
-                    ? `Configured environments: ${known.join(', ')}`
-                    : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
+        // Resolved once, so actors, step env, the browser driver and any spawned
+        // server all target the same place — including when the target only exists
+        // at run time and arrives through --api-url/--app-url.
+        const env = resolveScenarioEnvironment({
+            environment,
+            environments: config.scenarios?.environments ?? {},
+            apiUrl,
+            appUrl,
+            spawn,
+        });
+        if (apiUrl || appUrl) {
+            logger.info(`Overriding '${environment}': apiUrl ${env.apiUrl}${env.appUrl ? `, appUrl ${env.appUrl}` : ''}`);
         }
         if (spawn) {
             const { hostname, port } = new URL(env.apiUrl);

package/dist/src/functions/commands/skills.js

@@ -1,49 +1,25 @@
-import { readdir, readFile, mkdir, writeFile } from 'fs/promises';
+import { readdir, mkdir, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join, dirname, sep } from 'path';
-import { fileURLToPath } from 'url';
+import { dirname, join, sep } from 'path';
+import { listSkillFiles, listSkillNames, readSkillFile } from '@pikku/skills';
 import { pikkuSessionlessFunc } from '#pikku';
 /**
- * Walk up from this compiled file to find the package root (the directory
- * containing the @pikku/cli package.json), then resolve `<root>/skills/`.
- * Works whether the file is loaded from `dist/...` (published package) or
- * `src/...` (local dev via tsx/vitest).
+ * Write one skill's files out to `dest`, reading through @pikku/skills rather
+ * than off a directory we resolved ourselves. That package reads from its own
+ * `skills/` folder when there is one and from its embedded manifest otherwise,
+ * which is what makes this work inside the `bun --compile` binaries — they carry
+ * no filesystem copy, so the old "walk up to the @pikku/cli package root"
+ * lookup threw on every Homebrew install.
  */
-async function findSkillsDir() {
-    let dir = dirname(fileURLToPath(import.meta.url));
-    for (let i = 0; i < 8; i++) {
-        const pkgPath = join(dir, 'package.json');
-        if (existsSync(pkgPath)) {
-            try {
-                const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
-                if (pkg.name === '@pikku/cli') {
-                    const skills = join(dir, 'skills');
-                    if (existsSync(skills))
-                        return skills;
-                }
-            }
-            catch { }
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    throw new Error('Could not locate bundled skills directory. Was @pikku/cli installed correctly?');
-}
-async function copyDir(src, dest) {
-    await mkdir(dest, { recursive: true });
-    const entries = await readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-        const s = join(src, entry.name);
-        const d = join(dest, entry.name);
-        if (entry.isDirectory()) {
-            await copyDir(s, d);
-        }
-        else if (entry.isFile()) {
-            const content = await readFile(s);
-            await writeFile(d, content);
-        }
+async function writeSkill(name, dest) {
+    for (const path of await listSkillFiles(name)) {
+        const contents = await readSkillFile(path);
+        if (contents === null)
+            continue;
+        // Paths are relative to the skills root, so drop the leading skill name.
+        const target = join(dest, ...path.split('/').slice(1));
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, contents, 'utf-8');
     }
 }
 /**
@@ -82,17 +58,16 @@ function parseInstallGroups(frontmatter) {
     }
     return [];
 }
-async function readSkillInstallGroups(skillsDir, skillName) {
-    const skillPath = join(skillsDir, skillName, 'SKILL.md');
-    if (!existsSync(skillPath))
+async function readSkillInstallGroups(skillName) {
+    const content = await readSkillFile(`${skillName}/SKILL.md`);
+    if (content === null)
         return [];
-    const content = await readFile(skillPath, 'utf-8');
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match)
         return [];
     return parseInstallGroups(match[1]);
 }
-async function getWantedSkills(skillsDir, allEntries, { only, core = false, fabric = false, }) {
+async function getWantedSkills(allEntries, { only, core = false, fabric = false, }) {
     const wanted = new Set();
     if (only) {
         for (const name of only
@@ -108,7 +83,7 @@ async function getWantedSkills(skillsDir, allEntries, { only, core = false, fabr
     ];
     if (requestedGroups.length > 0) {
         for (const name of allEntries) {
-            const groups = await readSkillInstallGroups(skillsDir, name);
+            const groups = await readSkillInstallGroups(name);
             if (requestedGroups.some((group) => groups.includes(group))) {
                 wanted.add(name);
             }
@@ -118,11 +93,7 @@ async function getWantedSkills(skillsDir, allEntries, { only, core = false, fabr
 }
 export const pikkuSkillsList = pikkuSessionlessFunc({
     func: async ({ logger }) => {
-        const skillsDir = await findSkillsDir();
-        const entries = (await readdir(skillsDir, { withFileTypes: true }))
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
+        const entries = await listSkillNames();
         const installed = new Set();
         for (const relative of Object.values(AGENT_SKILL_DIRS)) {
             const dir = join(process.cwd(), relative);
@@ -154,12 +125,8 @@ export const pikkuSkillsInstall = pikkuSessionlessFunc({
             process.exitCode = 1;
             return;
         }
-        const skillsDir = await findSkillsDir();
-        const allEntries = (await readdir(skillsDir, { withFileTypes: true }))
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
-        const wanted = await getWantedSkills(skillsDir, allEntries, {
+        const allEntries = await listSkillNames();
+        const wanted = await getWantedSkills(allEntries, {
             only,
             core,
             fabric,
@@ -175,13 +142,12 @@ export const pikkuSkillsInstall = pikkuSessionlessFunc({
         let installed = 0;
         let skipped = 0;
         for (const name of wanted) {
-            const src = join(skillsDir, name);
             const dest = join(installRoot, name);
             if (existsSync(dest) && !update) {
                 skipped++;
                 continue;
             }
-            await copyDir(src, dest);
+            await writeSkill(name, dest);
             installed++;
         }
         const destLabel = `${AGENT_SKILL_DIRS[agent].split(sep).join('/')}/`;

package/dist/src/functions/db/db-codegen.d.ts

@@ -19,6 +19,12 @@ export interface CodegenOptions {
     rootDir?: string;
     /** DB dialect — drives real-type-aware date typing. Defaults to 'sqlite'. */
     dialect?: Dialect;
+    /**
+     * Where the project's migrations live. Only used to attribute each table in
+     * `schemaJsonFile` to whoever declared it; omitting it makes every table read
+     * as app-owned, which is what a project with no generated migrations is.
+     */
+    migrationsDir?: string;
 }
 export interface CodegenResult {
     outFile: string;

package/dist/src/functions/db/db-codegen.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { loadAnnotations, nameSuggestsKind, } from './annotation-parser.js';
 import { ZOD_FORMATS } from './zod-codegen.js';
+import { bareUnquotedTableName, readMigrationProvenance, } from './migration-provenance.js';
 import { ErrorCode } from '@pikku/inspector';
 /**
  * The column kind implied by the *real* DB type, dialect-aware. Postgres has
@@ -504,8 +505,16 @@ export async function generateSchemaTypes(introspector, options) {
     let schemaJsonBody = null;
     if (options.schemaJsonFile) {
         const fkMap = await introspector.getAllForeignKeys();
+        // Attribution comes from the migrations rather than from `schemaSources()`:
+        // the JSON is written by `db migrate`, which has no reason to load the
+        // project's Better Auth config, and the generated migrations already record
+        // both the source and its prose. See `readMigrationProvenance`.
+        const provenance = options.migrationsDir
+            ? readMigrationProvenance(options.migrationsDir)
+            : new Map();
         const jsonTables = tables.map((t) => ({
             name: t.name,
+            ...(provenance.get(bareUnquotedTableName(t.name)) ?? { source: 'app' }),
             columns: t.columns.map((c) => {
                 const fk = fkMap.get(t.name)?.find((f) => f.column === c.name);
                 return {

package/dist/src/functions/db/db-migrator.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { assertSnakeCaseIdentifiers } from './migration-identifiers.js';
 /**
  * The migrator's own bookkeeping table, which belongs to no dialect and to no
  * project's schema.
@@ -75,7 +76,20 @@ function assertNoDrift(applied, migrationsDir) {
         }
     }
 }
+/**
+ * Every migration on disk, read once.
+ *
+ * The identifier check reads all of them and not just the pending ones, so that
+ * whether a migration is rejected depends on the files alone. A camelCase
+ * column that had already been applied somewhere would otherwise pass on that
+ * machine and fail on a fresh checkout, which is the opposite of deterministic.
+ */
+const readMigrations = (migrationsDir) => migrationFiles(migrationsDir).map((name) => ({
+    name,
+    sql: readFileSync(join(migrationsDir, name), 'utf8'),
+}));
 export async function migrate(executor, migrationsDir) {
+    assertSnakeCaseIdentifiers(readMigrations(migrationsDir));
     await executor.ensureTrackingTable();
     const applied = await executor.getApplied();
     assertNoDrift(applied, migrationsDir);

package/dist/src/functions/db/local-db.d.ts

@@ -307,6 +307,14 @@ export interface GenerateResult {
  * Partially covered writes the delta, because re-emitting the whole schema
  * would fail on the tables that already exist.
  *
+ * The delta is itself two different things, and only one of them is a diff. A
+ * table the migrations already have but a column short is a genuine alteration,
+ * so it becomes `ALTER TABLE … ADD COLUMN`. A table they do not have at all —
+ * what enabling a Better Auth plugin or upgrading an addon produces — has
+ * nothing to diff against, so it is lifted verbatim out of the source's own SQL
+ * for the same reason the first-time case is: the column map it would otherwise
+ * be rendered from knows nothing about keys, constraints or indexes.
+ *
  * Migrations are written one file per source, numbered in dependency order, so
  * a project can review and apply them independently.
  */

package/dist/src/functions/db/local-db.js

@@ -10,6 +10,7 @@ import { loadAuthOptions, getAuthMigrations } from './better-auth-schema.js';
 import { generateSchemaTypes } from './db-codegen.js';
 import { generateZodTypes } from './zod-codegen.js';
 import { createCoercionPlugin } from './coercion-plugin.js';
+import { tableCreationSql } from './schema-sql.js';
 import { SqliteMigrationExecutor } from './sqlite/sqlite-migrator.js';
 import { SqliteIntrospector } from './sqlite/sqlite-introspector.js';
 import { createSqliteKysely } from './sqlite/sqlite-kysely.js';
@@ -190,6 +191,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
                 camelCase: resolved.camelCase,
                 rootDir: resolved.rootDir,
                 dialect: 'sqlite',
+                migrationsDir: resolved.migrationsDir,
             });
         }
         finally {
@@ -216,6 +218,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
                     camelCase: resolved.camelCase,
                     rootDir: resolved.rootDir,
                     dialect: 'postgres',
+                    migrationsDir: resolved.migrationsDir,
                 });
             }
             finally {
@@ -983,6 +986,14 @@ function addColumnStatements(table, columns) {
  * Partially covered writes the delta, because re-emitting the whole schema
  * would fail on the tables that already exist.
  *
+ * The delta is itself two different things, and only one of them is a diff. A
+ * table the migrations already have but a column short is a genuine alteration,
+ * so it becomes `ALTER TABLE … ADD COLUMN`. A table they do not have at all —
+ * what enabling a Better Auth plugin or upgrading an addon produces — has
+ * nothing to diff against, so it is lifted verbatim out of the source's own SQL
+ * for the same reason the first-time case is: the column map it would otherwise
+ * be rendered from knows nothing about keys, constraints or indexes.
+ *
  * Migrations are written one file per source, numbered in dependency order, so
  * a project can review and apply them independently.
  */
@@ -1009,9 +1020,20 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
         else {
             const statements = [];
             for (const table of missingTables) {
+                // A wholly new table is the first-time case in miniature: nothing to
+                // diff against, and the source's own SQL already says exactly how to
+                // build it. Rendering the column map instead would drop the primary
+                // key, the foreign keys and the indexes — a table that applies cleanly
+                // and is permanently wrong.
+                const own = tableCreationSql(source.desired.sql, table);
+                if (own.length > 0) {
+                    statements.push(own.join('\n\n'));
+                    continue;
+                }
                 const columns = source.desired.tables.get(table);
-                statements.push(`-- REVIEW: ${table} is new. Copy its CREATE TABLE from the source's own SQL —\n` +
-                    `-- the column list below carries no indexes, constraints or foreign keys.\n` +
+                statements.push(`-- REVIEW: ${table} is new, and its CREATE TABLE could not be found in the\n` +
+                    `-- source's own SQL. The column list below carries no indexes, constraints\n` +
+                    `-- or foreign keys — copy the real statement over it before applying.\n` +
                     `CREATE TABLE ${table} (\n` +
                     [...(columns?.values() ?? [])]
                         .map((c) => `  ${c.name} ${c.type}${c.notNull ? ' NOT NULL' : ''}`)

package/dist/src/functions/db/migration-identifiers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Catching camelCase columns at migrate time, before they can half-work.
+ *
+ * Pikku's Kysely runs with `CamelCasePlugin`, so `priceCents` in TypeScript is
+ * `price_cents` in SQL and nothing else. A migration that declares the column
+ * *as* `priceCents` is not merely unconventional — it is broken in the one way
+ * that hides itself: `.selectAll()` compiles to `SELECT *` and never names an
+ * identifier, so the table reads back perfectly, while the first query that
+ * names the column (`.select(['animal.priceCents'])`) asks for `price_cents`
+ * and gets `no such column`. The usual conclusion is that the plugin is broken,
+ * and the usual response is a raw `sql` template or a retreat to `.selectAll()`
+ * — both of which keep the real cause alive.
+ *
+ * There is no exception to escape. Even the Better Auth schema `db generate`
+ * writes is snake_case (`email_verified`, `user_id`), because Better Auth is
+ * handed the app's own Kysely and its camelCase field names compile the same
+ * way everyone else's do.
+ */
+/** A camelCase identifier a migration declares, and what it should have said. */
+export interface CamelCaseIdentifier {
+    file: string;
+    table: string;
+    /** `null` when the table name itself is the offender. */
+    column: string | null;
+    suggestion: string;
+}
+export declare class CamelCaseIdentifierError extends Error {
+    readonly offenders: CamelCaseIdentifier[];
+    constructor(offenders: CamelCaseIdentifier[]);
+}
+/**
+ * Strip comments so a word in prose can never be read as an identifier.
+ *
+ * `splitStatements` already skips over comments when it looks for a boundary,
+ * but it hands back the statement with them still in it, and `-- the userId
+ * column` would otherwise be flagged. Quoting rules are honoured for the same
+ * reason they are there: `'a -- b'` is a string, not a comment.
+ */
+export declare function stripSqlComments(sql: string): string;
+/**
+ * Every camelCase identifier one migration file declares.
+ *
+ * Only declarations are read — a `CREATE TABLE` column list and an `ALTER TABLE
+ * … ADD COLUMN`. Everywhere else an identifier merely refers to something that
+ * was declared somewhere, and reporting those would name the same mistake once
+ * per reference while adding nothing to the fix.
+ */
+export declare function findCamelCaseIdentifiers(file: string, sql: string): CamelCaseIdentifier[];
+/**
+ * Bail unless every migration on disk is snake_case throughout.
+ *
+ * Reports all of them at once: a camelCase column is rarely alone, and a
+ * one-at-a-time failure turns a single edit into one migrate run per column.
+ */
+export declare function assertSnakeCaseIdentifiers(migrations: Array<{
+    name: string;
+    sql: string;
+}>): void;