pgkiln 0.75.0 → 0.77.0

package/src/cli/advise.ts

@@ -0,0 +1,177 @@
+// (sprint 144, AP-10; APEX 26.2: APEXlang static analysis with SQLcl CodeScan) `pgkiln advise`: the builder's
+// Advisor from the command line, for CI. An export (directory, .zip or JSON) is imported into a transaction that is
+// always rolled back and checked there, like `pgkiln import --dry-run`; an application already in the database is
+// checked in place (also rolled back). Every SQL fragment is planned as the application's role, references are
+// followed, and the security defaults are checked (src/builder/advisor.ts). The findings come out as text, JSON or
+// SARIF 2.1.0 (GitHub code scanning annotates pull requests with it); each one points at the export's file of its
+// page or component when there is one.
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { docToFiles, slug, type FileMap } from '../appfiles.ts';
+import { exportDoc, importDoc, readSource, UsageError, type Db } from './apps.ts';
+
+export type Severity = 'error' | 'warning' | 'info';
+export const SEVERITIES: Severity[] = ['error', 'warning', 'info'];
+
+export interface AdviseFinding {
+  severity: Severity;
+  /** e.g. "page 3, region Employees", or "application" */
+  where: string;
+  field: string;
+  message: string;
+  /** the component's kind (region, item, lov …), for the SARIF rule, and its name */
+  kind: string | null;
+  label: string;
+  pageNo: number | null;
+  /** the export's file of the component (relative to the export's directory), when it has one */
+  file: string | null;
+}
+
+export interface AdviseResult {
+  alias: string;
+  /** where the files are, for the paths in the output: the export's directory (or null for an application) */
+  dir: string | null;
+  checked: number;
+  findings: AdviseFinding[];
+}
+
+const pad = (n: number) => String(n).padStart(4, '0');
+const stem = (path: string) => (path.split('/').pop() ?? '').replace(/\.[a-z]+$/, '').replace(/^\d{4}-/, '');
+
+/** The export's file of a component: its page's folder and its slug, a shared component by its slug, else the page or app file. */
+export function fileOf(files: string[], f: { pageNo: number | null; kind: string | null; label: string }): string | null {
+  const yaml = files.filter((p) => /\.(ya?ml|json)$/.test(p));
+  const name = slug(f.kind === 'page' ? '' : f.label);
+  if (f.pageNo !== null) {
+    const dir = yaml.filter((p) => p.startsWith(`pages/${pad(f.pageNo!)}-`));
+    if (!dir.length) return null;
+    const own = name ? dir.find((p) => !/\/page\.(ya?ml|json)$/.test(p) && stem(p) === name) : undefined;
+    return own ?? dir.find((p) => /\/page\.(ya?ml|json)$/.test(p)) ?? dir[0];
+  }
+  const shared = name ? yaml.find((p) => p.startsWith('shared/') && stem(p) === name) : undefined;
+  return shared ?? yaml.find((p) => /^app\.(ya?ml|json)$/.test(p)) ?? null;
+}
+
+/**
+ * Check an export (path) or an application in the database (alias). Nothing is ever committed: an export is
+ * imported under a temporary alias in a transaction that is rolled back.
+ */
+export async function adviseTarget(db: Db, target: string): Promise<AdviseResult> {
+  const { advise } = await import('../builder/advisor.ts');
+  let files: FileMap;
+  let dir: string | null = null;
+  let alias: string;
+  let id: number;
+  let checked = 0;
+  const findings: AdviseFinding[] = [];
+  const collect = async (appId: number) => {
+    const r = await advise(appId, db);
+    checked = r.checked;
+    for (const f of r.findings) {
+      const kind = f.entry?.kind ?? null;
+      const pageNo = f.entry?.pageNo ?? (/^Page (\d+)\b/.exec(f.field) ? Number(/^Page (\d+)\b/.exec(f.field)![1]) : null);
+      findings.push({
+        severity: f.severity,
+        where: f.entry ? (kind === 'page' ? f.entry.label : `${f.entry.pageNo !== null ? `page ${f.entry.pageNo}, ` : ''}${f.entry.kindLabel.toLowerCase()} ${f.entry.label}`) : pageNo !== null ? `page ${pageNo}` : 'application',
+        field: f.field,
+        message: f.message,
+        kind,
+        label: f.entry?.label ?? '',
+        pageNo,
+        file: null,
+      });
+    }
+  };
+  if (existsSync(target)) {
+    const source = await readSource(target);
+    files = source.files ?? docToFiles(source.doc);
+    dir = source.files ? target : null;
+    alias = String(source.doc?.app?.alias ?? 'app');
+    // a free alias for the check: the export's own may be taken by the application it came from
+    const temp = `advise-${process.pid}-${Date.now().toString(36)}`.slice(0, 40);
+    await db.query('begin');
+    try {
+      id = (await db.query('select meta.import_app($1::jsonb, $2) as id', [JSON.stringify(source.doc), temp])).rows[0].id;
+      await collect(id);
+    } finally {
+      await db.query('rollback');
+    }
+  } else {
+    if (/[/\\]|\.(json|zip)$/i.test(target)) throw new UsageError(`${target} not found`);
+    alias = target;
+    const row = (await db.query('select id from meta.app where alias = $1', [alias])).rows[0];
+    if (!row) throw new UsageError(`application ${alias} not found (pgkiln apps lists them), and no file or directory ${alias} exists`);
+    id = row.id;
+    files = docToFiles(await exportDoc(db, alias), 'text');
+    await db.query('begin');
+    try {
+      await collect(id);
+    } finally {
+      await db.query('rollback');
+    }
+  }
+  const paths = [...files.keys()];
+  for (const f of findings) f.file = fileOf(paths, f);
+  return { alias, dir, checked, findings };
+}
+
+// ------------------------------------------------------------------ output
+
+const order = (s: Severity) => SEVERITIES.indexOf(s);
+
+/** Whether the findings fail the run: any at or above the level ("never": no). */
+export function fails(findings: AdviseFinding[], failOn: Severity | 'never') {
+  return failOn !== 'never' && findings.some((f) => order(f.severity) <= order(failOn));
+}
+
+/** A finding's path for the output: inside the export's directory, relative to the current directory. */
+const pathOf = (r: AdviseResult, f: AdviseFinding, base: string | null) =>
+  f.file === null ? null : base !== null ? join(base, f.file).replace(/\\/g, '/') : r.dir ? relative(process.cwd(), join(r.dir, f.file)).replace(/\\/g, '/') : f.file;
+
+export function formatText(r: AdviseResult, base: string | null = null) {
+  const count = (s: Severity) => r.findings.filter((f) => f.severity === s).length;
+  return r.findings.map((f) => {
+    const path = pathOf(r, f, base);
+    return `${f.severity.toUpperCase().padEnd(7)} ${f.where}${f.field ? ` (${f.field})` : ''}: ${f.message}${path ? `\n        ${path}` : ''}\n`;
+  }).join('') + `${r.alias}: ${r.checked} SQL fragment(s) checked; ${count('error')} error(s), ${count('warning')} warning(s), ${count('info')} note(s).\n`;
+}
+
+export function formatJson(r: AdviseResult, base: string | null = null) {
+  return JSON.stringify({
+    alias: r.alias,
+    checked: r.checked,
+    counts: Object.fromEntries(SEVERITIES.map((s) => [s, r.findings.filter((f) => f.severity === s).length])),
+    findings: r.findings.map((f) => ({ severity: f.severity, where: f.where, field: f.field, message: f.message, page: f.pageNo, kind: f.kind, file: pathOf(r, f, base) })),
+  }, null, 2) + '\n';
+}
+
+/** A finding's rule: the component kind and the field (stable across runs, so code scanning can track it). */
+const ruleOf = (f: AdviseFinding) => `pgkiln/${f.kind ?? (f.pageNo !== null ? 'page' : 'application')}/${slug(f.field.replace(/^Page \d+ → /, '')) || 'check'}`;
+
+/** SARIF 2.1.0 (GitHub code scanning, other CI tools): one result per finding, at its file when it has one. */
+export function formatSarif(r: AdviseResult, version: string, base: string | null = null) {
+  const level = { error: 'error', warning: 'warning', info: 'note' } as const;
+  const rules = new Map<string, { id: string; shortDescription: { text: string } }>();
+  const results = r.findings.map((f) => {
+    const ruleId = ruleOf(f);
+    if (!rules.has(ruleId)) rules.set(ruleId, { id: ruleId, shortDescription: { text: `${f.kind ?? 'application'}: ${f.field || 'check'}` } });
+    const path = pathOf(r, f, base);
+    return {
+      ruleId,
+      level: level[f.severity],
+      message: { text: `${f.where}${f.field ? ` (${f.field})` : ''}: ${f.message}` },
+      locations: [{
+        ...(path ? { physicalLocation: { artifactLocation: { uri: path }, region: { startLine: 1 } } } : {}),
+        logicalLocations: [{ name: f.where, kind: 'object' }],
+      }],
+    };
+  });
+  return JSON.stringify({
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: { driver: { name: 'pgkiln advise', version, informationUri: 'https://github.com/pgkiln/pgkiln', rules: [...rules.values()] } },
+      results,
+    }],
+  }, null, 2) + '\n';
+}

package/src/cli/apps.ts

@@ -95,7 +95,7 @@ export async function importDoc(db: Db, doc: Doc, { alias, replace, check = 'off
       const { advise } = await import('../builder/advisor.ts');
       findings = (await advise(id, db)).findings.map((f) => ({
         severity: f.severity,
-        where: f.entry ? `${f.entry.pageNo !== null ? `page ${f.entry.pageNo}, ` : ''}${f.entry.kindLabel.toLowerCase()} ${f.entry.label}` : 'database',
+        where: f.entry ? (f.entry.kind === 'page' ? f.entry.label : `${f.entry.pageNo !== null ? `page ${f.entry.pageNo}, ` : ''}${f.entry.kindLabel.toLowerCase()} ${f.entry.label}`) : 'database',
         field: f.field,
         message: f.message,
       }));

package/src/cli/main.ts

@@ -84,6 +84,28 @@ async function checkPassword(password: string, username: string) {
   }
 }
 
+/** (sprint 144) pgkiln lock / unlock */
+async function lockCommand(v: Values, alias: string, what: 'lock' | 'unlock') {
+  const by = (v.as as string) ?? process.env.PGKILN_DEVELOPER ?? userInfo().username;
+  const page = v.page === undefined ? null : Number(v.page);
+  if (page !== null && !(Number.isInteger(page) && page > 0)) throw new UsageError('--page: a page number');
+  process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
+  const wc = await import('./working-copy.ts');
+  const { closePools } = await import('../db.ts');
+  try {
+    out(what === 'lock' ? await wc.lockApp(alias, page, by, (v.note as string) ?? null) : await wc.unlockApp(alias, page, by, !!v.force));
+    return EXIT.ok;
+  } catch (e) {
+    if (e instanceof wc.WorkingCopyError) {
+      err(`pgkiln ${what}: ${e.message}\n`);
+      return EXIT.differences;
+    }
+    throw e;
+  } finally {
+    await closePools();
+  }
+}
+
 // ------------------------------------------------------------------ commands
 
 const COMMANDS: Record<string, Command> = {
@@ -309,6 +331,133 @@ const COMMANDS: Record<string, Command> = {
     },
   },
 
+  advise: {
+    usage: 'pgkiln advise <path | alias> [--format text|json|sarif] [--fail-on error|warning|info|never] [-o <file>]',
+    summary: 'check an export or an application with the Advisor (for CI: text, JSON or SARIF)',
+    details:
+      'Runs the builder\'s Advisor: every SQL fragment is planned as the application\'s database role (unknown\n' +
+      'tables, columns, functions, types and missing grants), references to pages, items, lists of values and\n' +
+      'schemes are followed, and security defaults are checked (pages that write data without sign-in or an\n' +
+      'authorization scheme, unrestricted page protection, long sessions, administrators without a second factor).\n\n' +
+      'A path (an export directory, a .zip or a JSON export) is imported into a transaction that is rolled back:\n' +
+      'nothing changes. It needs a database with pgkiln\'s migrations and the application\'s own tables (in CI, a\n' +
+      'PostgreSQL service, pgkiln migrate and your migrations). An alias checks the application in the database.\n\n' +
+      'SARIF points every finding at the file of its page or component in the export, so GitHub code scanning\n' +
+      'annotates the pull request. Exit code 1 when a finding is at or above --fail-on (default: error).',
+    options: { format: { type: 'string', short: 'f' }, 'fail-on': { type: 'string' }, output: { type: 'string', short: 'o' }, base: { type: 'string' } },
+    optionHelp: [
+      ['-f, --format <format>', 'text (default), json or sarif'],
+      ['--fail-on <level>', 'exit code 1 from this level: error (default), warning, info or never'],
+      ['-o, --output <file>', 'write the report to a file (the summary still goes to standard error)'],
+      ['--base <dir>', 'with an alias: the folder its export lives in, for the paths in the report (e.g. apps/hr)'],
+    ],
+    positionals: [1, 1],
+    async run(v, [target]) {
+      const format = (v.format as string) ?? 'text';
+      const failOn = (v['fail-on'] as string) ?? 'error';
+      if (!['text', 'json', 'sarif'].includes(format)) throw new UsageError(`--format: text, json or sarif, not ${format}`);
+      if (!['error', 'warning', 'info', 'never'].includes(failOn)) throw new UsageError(`--fail-on: error, warning, info or never, not ${failOn}`);
+      process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
+      const { adviseTarget, fails, formatJson, formatSarif, formatText } = await import('./advise.ts');
+      const { closePools } = await import('../db.ts');
+      try {
+        const r = await withDb((db) => adviseTarget(db, target));
+        const base = (v.base as string) ?? null;
+        const report = format === 'sarif' ? formatSarif(r, version(), base) : format === 'json' ? formatJson(r, base) : formatText(r, base);
+        if (v.output) {
+          writeFileSync(v.output as string, report);
+          const count = (s: string) => r.findings.filter((f) => f.severity === s).length;
+          err(`${r.alias}: ${count('error')} error(s), ${count('warning')} warning(s), ${count('info')} note(s); report in ${v.output}.\n`);
+        } else out(report);
+        return fails(r.findings, failOn as 'error') ? EXIT.differences : EXIT.ok;
+      } finally {
+        await closePools();
+      }
+    },
+  },
+
+  'working-copy': {
+    usage: 'pgkiln working-copy <list|create|compare|merge|refresh|delete> <alias> [<name>] [--prefer copy|main] [--take <component>]… [--as <developer>]',
+    summary: 'make, compare, merge and delete working copies of an application',
+    details:
+      'list <alias>             the working copies of an application\n' +
+      'create <alias> <name>    a working copy of the application (a new application, alias printed)\n' +
+      'compare <copy>           the components that differ from the main application (exit 1 with conflicts)\n' +
+      'merge <copy>             the copy\'s changes into the main application\n' +
+      'refresh <copy>           the main application\'s changes into the copy\n' +
+      'delete <copy>            delete the working copy\n\n' +
+      'Conflicts (a component changed on both sides) need a choice: --prefer copy or --prefer main for all, or\n' +
+      '--take <component> (as compare lists them) for each one that keeps the copy\'s version. A merge is refused\n' +
+      'while another developer has locked the target application or a page it changes. Changes are logged under\n' +
+      '--as, else PGKILN_DEVELOPER, else the operating system user.',
+    options: { prefer: { type: 'string' }, take: { type: 'string', multiple: true }, as: { type: 'string' } },
+    optionHelp: [
+      ['--prefer copy|main', 'merge, refresh: resolve every conflict this way'],
+      ['--take <component>', 'merge, refresh: this conflict keeps the copy\'s version (repeat)'],
+      ['--as <developer>', 'who does it (activity log, locks)'],
+    ],
+    positionals: [2, 3],
+    async run(v, [action, alias, name]) {
+      const by = (v.as as string) ?? process.env.PGKILN_DEVELOPER ?? userInfo().username;
+      const prefer = v.prefer as string | undefined;
+      if (prefer !== undefined && prefer !== 'copy' && prefer !== 'main') throw new UsageError('--prefer: copy or main');
+      process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
+      const wc = await import('./working-copy.ts');
+      const { closePools } = await import('../db.ts');
+      try {
+        switch (action) {
+          case 'list': out(await wc.listCopies(alias)); return EXIT.ok;
+          case 'create':
+            if (!name) throw new UsageError('create needs a name: pgkiln working-copy create <alias> <name>');
+            out((await wc.createWorkingCopy(alias, name, by)).text);
+            return EXIT.ok;
+          case 'compare': {
+            const c = await wc.compareCopy(alias);
+            out(c.text);
+            return c.conflicts ? EXIT.differences : EXIT.ok;
+          }
+          case 'merge':
+          case 'refresh':
+            out(await wc.mergeWorkingCopy(alias, { direction: action, prefer: (prefer as 'copy' | 'main') ?? null, take: (v.take as unknown as string[] | undefined) ?? [], by }));
+            return EXIT.ok;
+          case 'delete': out(await wc.deleteWorkingCopy(alias, by)); return EXIT.ok;
+          default: throw new UsageError(`unknown action ${action}: list, create, compare, merge, refresh or delete`);
+        }
+      } catch (e) {
+        if (e instanceof wc.WorkingCopyError) {
+          err(`pgkiln working-copy: ${e.message}\n`);
+          return EXIT.differences;
+        }
+        throw e;
+      } finally {
+        await closePools();
+      }
+    },
+  },
+
+  lock: {
+    usage: 'pgkiln lock <alias> [--page <n>] [--note <text>] [--as <developer>]',
+    summary: 'lock an application or one of its pages, as the builder\'s Lock does',
+    details: 'Other developers can\'t change it in the builder, import over it or merge into it until it is unlocked.',
+    options: { page: { type: 'string', short: 'p' }, note: { type: 'string' }, as: { type: 'string' } },
+    optionHelp: [['-p, --page <n>', 'lock this page only'], ['--note <text>', 'why (shown to the others)'], ['--as <developer>', 'whose lock (default PGKILN_DEVELOPER or the operating system user)']],
+    positionals: [1, 1],
+    async run(v, [alias]) {
+      return lockCommand(v, alias, 'lock');
+    },
+  },
+
+  unlock: {
+    usage: 'pgkiln unlock <alias> [--page <n>] [--force] [--as <developer>]',
+    summary: 'unlock an application or a page (another developer\'s lock only with --force, logged)',
+    options: { page: { type: 'string', short: 'p' }, force: { type: 'boolean' }, as: { type: 'string' } },
+    optionHelp: [['-p, --page <n>', 'unlock this page'], ['--force', 'break another developer\'s lock (logged)'], ['--as <developer>', 'who unlocks']],
+    positionals: [1, 1],
+    async run(v, [alias]) {
+      return lockCommand(v, alias, 'unlock');
+    },
+  },
+
   mcp: {
     usage: 'pgkiln mcp',
     summary: 'run an MCP server on standard input/output for AI coding agents (Claude Code, Cursor, …)',

package/src/cli/mcp.ts

@@ -427,6 +427,99 @@ export const TOOLS: Tool[] = [
       );
     },
   },
+  // (sprint 144, AP-10) the Advisor and working copies, as `pgkiln advise` / `pgkiln working-copy` / `pgkiln lock`
+  {
+    name: 'advise_app',
+    title: 'Check an application with the Advisor',
+    description:
+      'Runs the Advisor on an export directory, zip or JSON file (imported into a transaction that is rolled back: nothing changes) ' +
+      'or on the application in the database: every SQL fragment planned as the application\'s role, references to pages, items, ' +
+      'lists of values and schemes, and security defaults (pages that write data without sign-in or an authorization scheme, ' +
+      'unrestricted page protection, long sessions, administrators without a second factor). Each finding names its file in the export.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...aliasProp, path: { type: 'string', description: 'an export directory, .zip or .json instead of the application in the database' } },
+    },
+    annotations: { readOnlyHint: true },
+    async run(a) {
+      const path = str(a, 'path');
+      const alias = str(a, 'alias');
+      if (!path && !alias) throw new ToolError('give an alias or a path');
+      process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
+      const { adviseTarget, formatText } = await import('./advise.ts');
+      return cap(formatText(await withDb((db) => adviseTarget(db, path ? resolve(path) : alias!))));
+    },
+  },
+  {
+    name: 'working_copy',
+    title: 'Working copies of an application',
+    description:
+      'Work on a copy of an application and merge it back, as App Builder → Working copies does. action: list (the copies of alias), ' +
+      'create (a copy named name; its alias is returned: export, change and import that one), compare (the components that differ from the ' +
+      'main application: copy, main or CONFLICT, with ids), merge (the copy\'s changes into the main application), refresh (the main ' +
+      'application\'s changes into the copy) or delete. Conflicts need prefer (copy or main) or take (the conflict ids that keep the copy\'s ' +
+      'version). A merge is refused while another developer has locked the target application or a page it changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'create', 'compare', 'merge', 'refresh', 'delete'] },
+        alias: { type: 'string', description: 'the main application (list, create) or the working copy (compare, merge, refresh, delete)' },
+        name: { type: 'string', description: 'create: the copy\'s name (letters, digits, spaces, - and _)' },
+        prefer: { type: 'string', enum: ['copy', 'main'], description: 'merge, refresh: how to resolve every conflict' },
+        take: { type: 'array', items: { type: 'string' }, description: 'merge, refresh: conflict ids (from compare) that keep the copy\'s version' },
+        developer: { type: 'string', description: 'who does it, for the activity log and locks (default: MCP)' },
+      },
+      required: ['action', 'alias'],
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true },
+    async run(a) {
+      const action = str(a, 'action', true)!;
+      const alias = str(a, 'alias', true)!;
+      const by = str(a, 'developer') ?? 'MCP';
+      const prefer = str(a, 'prefer');
+      if (prefer && prefer !== 'copy' && prefer !== 'main') throw new ToolError('prefer: copy or main');
+      const take = Array.isArray(a.take) ? (a.take as unknown[]).filter((x): x is string => typeof x === 'string') : [];
+      process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
+      const wc = await import('./working-copy.ts');
+      switch (action) {
+        case 'list': return wc.listCopies(alias);
+        case 'create': return (await wc.createWorkingCopy(alias, str(a, 'name', true)!, by)).text;
+        case 'compare': return cap((await wc.compareCopy(alias)).text);
+        case 'merge':
+        case 'refresh': return wc.mergeWorkingCopy(alias, { direction: action, prefer: (prefer as 'copy' | 'main' | undefined) ?? null, take, by });
+        case 'delete': return wc.deleteWorkingCopy(alias, by);
+        default: throw new ToolError('action: list, create, compare, merge, refresh or delete');
+      }
+    },
+  },
+  {
+    name: 'lock_app',
+    title: 'Lock or unlock an application or page',
+    description:
+      'Locks an application (or one page) so other developers can\'t change it, import over it or merge into it, as the builder\'s Lock does; ' +
+      'unlock=true removes the lock (another developer\'s lock only with force=true, which is logged).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...aliasProp,
+        page: { type: 'integer', description: 'lock this page only' },
+        unlock: { type: 'boolean' },
+        force: { type: 'boolean', description: 'with unlock: break another developer\'s lock' },
+        note: { type: 'string', description: 'why (shown to other developers)' },
+        developer: { type: 'string', description: 'whose lock (default: MCP)' },
+      },
+      required: ['alias'],
+    },
+    annotations: { readOnlyHint: false },
+    async run(a) {
+      const alias = str(a, 'alias', true)!;
+      const page = a.page === undefined || a.page === null ? null : int(a, 'page', 1, 1_000_000);
+      const by = str(a, 'developer') ?? 'MCP';
+      process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
+      const wc = await import('./working-copy.ts');
+      return a.unlock === true ? wc.unlockApp(alias, page, by, a.force === true) : wc.lockApp(alias, page, by, str(a, 'note') ?? null);
+    },
+  },
   {
     name: 'describe_schema',
     title: 'Describe database objects',

package/src/cli/working-copy.ts

@@ -0,0 +1,121 @@
+// (sprint 144, AP-10; APEX 26.2: the Application and Working Copy APIs for CI / CD) Working copies and builder
+// locks from the command line (`pgkiln working-copy …`, `pgkiln lock` / `unlock`) and the MCP server, with the same
+// rules as the builder (src/builder/workingcopies.ts, locks.ts): a copy is made, compared per component with its
+// main application (three ways), merged back or refreshed; a merge is refused while another developer has locked the
+// target or a page it changes; conflicts need a choice (prefer the copy's or the main version). Every change is in
+// the activity log under the developer named (--as, PGKILN_DEVELOPER or the operating system user). The functions
+// return text and throw WorkingCopyError for what the user must fix.
+import { owner } from '../db.ts';
+import { logActivity } from '../session.ts';
+import { compare, copiesOf, copyOf, createCopy, deleteCopy, fingerprint, mergeCopy, WorkingCopyError, type Change } from '../workingcopy.ts';
+import { lockText, type Lock } from '../builder/locks.ts';
+
+export { WorkingCopyError };
+
+const IP = 'cli';
+
+async function appByAlias(alias: string) {
+  const a = await owner.one<{ id: number; alias: string; name: string }>('select id, alias, name from meta.app where alias = $1', [alias]);
+  if (!a) throw new WorkingCopyError(`Application ${alias} not found.`);
+  return a;
+}
+
+/** Another developer's lock on an application or one of the pages a merge changes (as the builder's merge). */
+export const lockedFor = (username: string) => async (appId: number, pages: Set<number>) => {
+  const l = await owner.one<Lock>(
+    `select app_id, page_no, locked_by, locked_at::text, note from meta.builder_lock
+      where app_id = $1 and locked_by <> $2 and (page_no = 0 or page_no = any($3::int[])) order by page_no limit 1`,
+    [appId, username, [...pages]],
+  );
+  return l ? `${lockText(l)} The change is refused until it is unlocked.` : null;
+};
+
+/** The working copies of an application (alias of the main application or of a copy). */
+export async function listCopies(alias: string) {
+  const a = await appByAlias(alias);
+  const wc = await copyOf(a.id);
+  const mainId = wc ? wc.main_app_id : a.id;
+  const copies = await copiesOf(mainId);
+  if (!copies.length) return `${alias} has no working copies.\n`;
+  return copies.map((c) => `${c.alias}\t${c.name}\tby ${c.created_by} ${c.created_at.slice(0, 16)}${c.merged_at ? `\tmerged ${c.merged_at.slice(0, 16)}` : ''}${c.refreshed_at ? `\trefreshed ${c.refreshed_at.slice(0, 16)}` : ''}\n`).join('');
+}
+
+export async function createWorkingCopy(alias: string, name: string, by: string) {
+  const a = await appByAlias(alias);
+  if (await copyOf(a.id)) throw new WorkingCopyError(`${alias} is itself a working copy: make the copy from its main application.`);
+  const id = await createCopy(a.id, name, by);
+  const copy = await owner.one<{ alias: string }>('select alias from meta.app where id = $1', [id]);
+  await logActivity({ appId: a.id, username: by, event: 'working_copy', ip: IP, detail: `created ${name} (application ${id})` });
+  return { id, alias: copy!.alias, text: `Working copy ${name} of ${alias}: application ${copy!.alias} (${id}).\n` };
+}
+
+const STATUS: Record<Change['status'], string> = { copy: 'copy', main: 'main', conflict: 'CONFLICT' };
+
+/** The comparison of a working copy with its main application, one component per line. */
+export async function compareCopy(alias: string) {
+  const a = await appByAlias(alias);
+  const l = await compare(a.id);
+  if (!l) throw new WorkingCopyError(`${alias} is not a working copy.`);
+  const conflicts = l.changes.filter((c) => c.status === 'conflict');
+  const text = l.changes.length
+    ? l.changes.map((c) => `${STATUS[c.status].padEnd(8)} ${c.label}  [${c.id}]\n`).join('') +
+      `${l.changes.length} component(s) differ from ${l.mainAlias}: ${l.changes.filter((c) => c.status === 'copy').length} changed in the copy, ` +
+      `${l.changes.filter((c) => c.status === 'main').length} in the main application, ${conflicts.length} conflict(s).\n`
+    : `${alias} and ${l.mainAlias} are the same: nothing to merge.\n`;
+  return { changes: l.changes, conflicts: conflicts.length, mainAlias: l.mainAlias, text };
+}
+
+/**
+ * Merge a working copy into its main application ('merge') or bring the main application's changes into the copy
+ * ('refresh'). Conflicts need prefer ('copy' or 'main' for all of them) or take (component ids that keep the copy's
+ * version; the others keep the main's).
+ */
+export async function mergeWorkingCopy(alias: string, o: { direction: 'merge' | 'refresh'; prefer?: 'copy' | 'main' | null; take?: string[]; by: string }) {
+  const a = await appByAlias(alias);
+  const l = await compare(a.id);
+  if (!l) throw new WorkingCopyError(`${alias} is not a working copy.`);
+  const conflicts = l.changes.filter((c) => c.status === 'conflict');
+  const take = new Set(o.take ?? []);
+  for (const id of take) if (!conflicts.some((c) => c.id === id)) throw new WorkingCopyError(`${id} is not one of the conflicts.`);
+  if (o.prefer === 'copy') conflicts.forEach((c) => take.add(c.id));
+  const open = conflicts.filter((c) => !take.has(c.id) && o.prefer !== 'main' && !(o.take?.length));
+  if (open.length)
+    throw new WorkingCopyError(`${open.length} conflict(s): choose the copy's or the main version (prefer copy|main, or take <component> for those that keep the copy's):\n` +
+      open.map((c) => `  ${c.label}  [${c.id}]`).join('\n'));
+  const r = await mergeCopy(a.id, { direction: o.direction, takeCopy: take, state: fingerprint(l.changes), username: o.by, lockedBy: lockedFor(o.by) });
+  await logActivity({ appId: o.direction === 'merge' ? r.mainId : a.id, username: o.by, event: 'working_copy', ip: IP, detail: `${o.direction === 'merge' ? 'merged' : 'refreshed'} ${l.copy.name} (${r.changes} components)` });
+  return o.direction === 'merge' ? `Merged ${alias} into ${l.mainAlias} (${r.changes} component(s)).\n` : `Refreshed ${alias} from ${l.mainAlias} (${r.changes} component(s)).\n`;
+}
+
+export async function deleteWorkingCopy(alias: string, by: string) {
+  const a = await appByAlias(alias);
+  const wc = await copyOf(a.id);
+  if (!wc) throw new WorkingCopyError(`${alias} is not a working copy: only working copies are deleted here.`);
+  await deleteCopy(a.id);
+  await logActivity({ appId: wc.main_app_id, username: by, event: 'working_copy', ip: IP, detail: `deleted ${wc.name}` });
+  return `Deleted working copy ${wc.name} (${alias}).\n`;
+}
+
+/** Lock an application (page null) or one of its pages for the developer, as the builder's Lock does. */
+export async function lockApp(alias: string, page: number | null, by: string, note: string | null) {
+  const a = await appByAlias(alias);
+  if (page !== null && !(await owner.one('select 1 as ok from meta.page where app_id = $1 and page_no = $2', [a.id, page]))) throw new WorkingCopyError(`${alias} has no page ${page}.`);
+  const r = await owner.query(`insert into meta.builder_lock (app_id, page_no, locked_by, note) values ($1, $2, $3, $4) on conflict (app_id, page_no) do nothing`,
+    [a.id, page ?? 0, by, note?.slice(0, 500) || null]);
+  if (!r.rowCount) {
+    const l = await owner.one<Lock>('select app_id, page_no, locked_by, locked_at::text, note from meta.builder_lock where app_id = $1 and page_no = $2', [a.id, page ?? 0]);
+    throw new WorkingCopyError(l ? lockText(l) : 'It is already locked.');
+  }
+  return `${page ? `Page ${page} of ${alias}` : alias} is locked by ${by}.\n`;
+}
+
+/** Unlock; another developer's lock only with force (logged as a broken lock, as an administrator does in the builder). */
+export async function unlockApp(alias: string, page: number | null, by: string, force: boolean) {
+  const a = await appByAlias(alias);
+  const l = await owner.one<Lock>('select app_id, page_no, locked_by, locked_at::text, note from meta.builder_lock where app_id = $1 and page_no = $2', [a.id, page ?? 0]);
+  if (!l) return 'It is not locked.\n';
+  if (l.locked_by !== by && !force) throw new WorkingCopyError(`${lockText(l)} Only ${l.locked_by} unlocks it (or use --force).`);
+  await owner.query('delete from meta.builder_lock where app_id = $1 and page_no = $2', [a.id, page ?? 0]);
+  if (l.locked_by !== by) await logActivity({ appId: a.id, pageNo: page, username: by, event: 'lock_broken', ip: IP, detail: `command line: lock of ${l.locked_by}` });
+  return l.locked_by === by ? 'Unlocked.\n' : `${l.locked_by}'s lock was broken.\n`;
+}

package/src/i18n/ar.ts

@@ -475,6 +475,30 @@ export const ar: Record<MessageKey, string> = {
   'op.not_contains': "لا يحتوي على",
   'op.null': "فارغ",
   'op.not_null': "غير فارغ",
+  'op.in': "أحد",
+  'op.not_in': "ليس أيًا من",
+  'op.between': "بين",
+  'op.period': "ضمن",
+  'report.value_to': "إلى",
+  'report.values': "القيم",
+  'report.period': "الفترة",
+  'report.and': "و",
+  'report.filter_help': "أحد: قيم مفصولة بفواصل أو محددة في القائمة. بين: يمكن ترك إحدى القيمتين فارغة. ضمن: فترة لعمود تاريخ.",
+  'report.order_chip': "ترتيب أعمدة خاص",
+  'report.order_reset': "العودة إلى ترتيب أعمدة التقرير",
+  'report.order_help': "اسحب عمودًا أو استخدم الأسهم لتغيير الترتيب.",
+  'report.move_up': "نقل {column} لأعلى",
+  'report.move_down': "نقل {column} لأسفل",
+  'report.moved': "{column}: الموضع {n} من {total}",
+  'period.today': "اليوم",
+  'period.yesterday': "أمس",
+  'period.last_7_days': "آخر 7 أيام",
+  'period.last_30_days': "آخر 30 يومًا",
+  'period.next_7_days': "الأيام السبعة القادمة",
+  'period.this_month': "هذا الشهر",
+  'period.last_month': "الشهر الماضي",
+  'period.this_year': "هذه السنة",
+  'period.last_year': "السنة الماضية",
   'grid.delete_row': "حذف الصف {row}",
   'grid.new': "جديد",
   'grid.row_changed': "الصف {row}: تم تغيير هذا الصف خارج الشبكة؛ أعد تحميل الصفحة.",

package/src/i18n/cs.ts

@@ -475,6 +475,30 @@ export const cs: Record<MessageKey, string> = {
   'op.not_contains': "neobsahuje",
   'op.null': "je prázdné",
   'op.not_null': "není prázdné",
+  'op.in': "je jedno z",
+  'op.not_in': "není žádné z",
+  'op.between': "je mezi",
+  'op.period': "je v",
+  'report.value_to': "Do",
+  'report.values': "Hodnoty",
+  'report.period': "Období",
+  'report.and': "a",
+  'report.filter_help': "Je jedno z: hodnoty oddělené čárkami nebo zaškrtnuté v seznamu. Je mezi: jedna z hodnot může zůstat prázdná. Je v: období sloupce s datem.",
+  'report.order_chip': "Vlastní pořadí sloupců",
+  'report.order_reset': "Zpět na pořadí sloupců sestavy",
+  'report.order_help': "Přetáhněte sloupec nebo použijte šipky ke změně pořadí.",
+  'report.move_up': "Posunout {column} nahoru",
+  'report.move_down': "Posunout {column} dolů",
+  'report.moved': "{column}: pozice {n} z {total}",
+  'period.today': "dnes",
+  'period.yesterday': "včera",
+  'period.last_7_days': "posledních 7 dnech",
+  'period.last_30_days': "posledních 30 dnech",
+  'period.next_7_days': "příštích 7 dnech",
+  'period.this_month': "tomto měsíci",
+  'period.last_month': "minulém měsíci",
+  'period.this_year': "tomto roce",
+  'period.last_year': "minulém roce",
   'grid.delete_row': "Smazat řádek {row}",
   'grid.new': "nový",
   'grid.row_changed': "Řádek {row}: tento řádek byl změněn mimo mřížku; načtěte stránku znovu.",