@pathmx/core 0.5.0

package/cli/perms.ts

@@ -0,0 +1,182 @@
+import type { Command } from "commander"
+import type {
+  SourceAccessBasis,
+  SourcePermissionRecord,
+} from "../authority/access.ts"
+import type { Engine } from "../host/engine.ts"
+import { Log } from "../log.ts"
+import type { Source } from "../source/index.ts"
+import { fail, loadApp, rootFromCommand } from "./utils.ts"
+
+type PermissionFormat = "text" | "json"
+
+type PermissionReport =
+  | Readonly<{
+      type: "source"
+      sourceId: string
+      actorId?: string
+      permissions: readonly SourcePermissionRecord[]
+    }>
+  | Readonly<{
+      type: "actor"
+      actorId: string
+      permissions: readonly SourcePermissionRecord[]
+    }>
+
+type PermissionQuery =
+  | Readonly<{ source: Source; actorId?: string }>
+  | Readonly<{ source?: never; actorId: string }>
+
+function formatOption(value: string): PermissionFormat {
+  if (value === "text" || value === "json") return value
+  throw new Error(`Unsupported permission format: ${value}`)
+}
+
+function capabilityText(record: SourcePermissionRecord) {
+  const granted = new Set(record.capabilities)
+  return `${granted.has("read") ? "r" : "-"}${granted.has("write") ? "w" : "-"}${granted.has("execute") ? "x" : "-"}`
+}
+
+function basisText(basis: SourceAccessBasis) {
+  switch (basis.type) {
+    case "exact-grant":
+      return basis.owner ? "owner · exact grant" : "exact grant"
+    case "home-owner":
+      return "Home owner"
+    case "staff-review":
+      return "staff review"
+    case "public-source":
+      return "public Source"
+    case "denied":
+      return basis.reason.replaceAll("-", " ")
+  }
+}
+
+function table(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[],
+) {
+  const widths = headers.map((header, column) =>
+    Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)),
+  )
+  return [headers, ...rows]
+    .map((row) =>
+      row
+        .map((cell, column) => cell.padEnd(widths[column] ?? cell.length))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n")
+}
+
+function textReport(report: PermissionReport) {
+  if (report.type === "source") {
+    return [
+      report.sourceId,
+      table(
+        ["Actor", "Caps", "Visibility", "Basis"],
+        report.permissions.map((record) => [
+          record.actorId ?? "anonymous",
+          capabilityText(record),
+          record.visibility,
+          basisText(record.basis),
+        ]),
+      ),
+    ].join("\n\n")
+  }
+  return [
+    report.actorId,
+    table(
+      ["Caps", "Source", "Visibility", "Basis"],
+      report.permissions.map((record) => [
+        capabilityText(record),
+        record.sourceId,
+        record.visibility,
+        basisText(record.basis),
+      ]),
+    ),
+  ].join("\n\n")
+}
+
+function sourceFor(app: Engine, target: string) {
+  return app.repo.get(target) ?? app.repo.atPath(target)
+}
+
+export function permissionReport(
+  app: Engine,
+  options: PermissionQuery,
+): PermissionReport {
+  if (options.source) {
+    let permissions = app.inspectSourcePermissions(options.source)
+    if (options.actorId) {
+      permissions = permissions.filter(
+        (record) => record.actorId === options.actorId,
+      )
+      if (!permissions.length)
+        throw new Error(`Actor not found: ${options.actorId}`)
+    }
+    return {
+      type: "source",
+      sourceId: options.source.id,
+      ...(options.actorId ? { actorId: options.actorId } : {}),
+      permissions,
+    }
+  }
+
+  const permissions = app.inspectActorPermissions(options.actorId)
+  if (!permissions) throw new Error(`Actor not found: ${options.actorId}`)
+  return {
+    type: "actor",
+    actorId: options.actorId,
+    permissions: permissions.filter((record) =>
+      record.capabilities.includes("read"),
+    ),
+  }
+}
+
+export function registerPerms(program: Command) {
+  program
+    .command("perms")
+    .description("Inspect effective Source permissions")
+    .argument("[source]", "Source id or path")
+    .option("--as <actor>", "inspect permissions for an Actor id")
+    .option(
+      "--format <format>",
+      "output format: text or json",
+      formatOption,
+      "text",
+    )
+    .action(
+      async (
+        target: string | undefined,
+        opts: { as?: string; format: PermissionFormat },
+        command: Command,
+      ) => {
+        try {
+          const resolved = rootFromCommand(command)
+          const app = await loadApp(resolved.root, {
+            actionsRoot: resolved.actionsRoot,
+            buildCache: false,
+            log: new Log({ level: "error" }),
+          })
+          const source = target ? sourceFor(app, target) : undefined
+          if (target && !source) throw new Error(`Source not found: ${target}`)
+          let report: PermissionReport
+          if (source) {
+            report = permissionReport(app, { source, actorId: opts.as })
+          } else {
+            if (!opts.as)
+              throw new Error("Provide a Source or use --as <actor>.")
+            report = permissionReport(app, { actorId: opts.as })
+          }
+          console.log(
+            opts.format === "json"
+              ? JSON.stringify(report, null, 2)
+              : textReport(report),
+          )
+        } catch (error) {
+          fail(error)
+        }
+      },
+    )
+}

package/cli/plugin-packages.ts

@@ -0,0 +1,159 @@
+import { dirname, join } from "node:path"
+import type { Command } from "commander"
+import { release } from "./release.ts"
+import { rootFromCommand } from "./utils.ts"
+
+type ProjectManifest = Readonly<{
+  dependencies?: Readonly<Record<string, string>>
+  devDependencies?: Readonly<Record<string, string>>
+  optionalDependencies?: Readonly<Record<string, string>>
+}>
+
+type InstalledPlugin = Readonly<{
+  name: string
+  spec: string
+  development: boolean
+}>
+
+export function pluginPackageName(input: string) {
+  const name = input.startsWith("@pathmx/") ? input.slice(8) : input
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) {
+    throw new Error(
+      `Invalid PathMX plugin package: ${input}. Use a name such as react or @pathmx/react.`,
+    )
+  }
+  return `@pathmx/${name}`
+}
+
+function projectRoot(command: Command) {
+  return dirname(rootFromCommand(command).root)
+}
+
+async function projectManifest(root: string) {
+  const file = Bun.file(join(root, "package.json"))
+  if (!(await file.exists())) {
+    throw new Error(`PathMX project package.json not found: ${file.name}`)
+  }
+  return (await file.json()) as ProjectManifest
+}
+
+function installedPlugins(manifest: ProjectManifest) {
+  const plugins = new Map<string, InstalledPlugin>()
+  for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
+    if (name.startsWith("@pathmx/")) {
+      plugins.set(name, { name, spec, development: false })
+    }
+  }
+  for (const [name, spec] of Object.entries(
+    manifest.optionalDependencies ?? {},
+  )) {
+    if (name.startsWith("@pathmx/") && !plugins.has(name)) {
+      plugins.set(name, { name, spec, development: false })
+    }
+  }
+  for (const [name, spec] of Object.entries(manifest.devDependencies ?? {})) {
+    if (name.startsWith("@pathmx/") && !plugins.has(name)) {
+      plugins.set(name, { name, spec, development: true })
+    }
+  }
+  return [...plugins.values()].sort((left, right) =>
+    left.name.localeCompare(right.name),
+  )
+}
+
+async function resolvedVersion(root: string, name: string) {
+  const manifest = Bun.file(join(root, "node_modules", name, "package.json"))
+  if (!(await manifest.exists())) return undefined
+  const value = (await manifest.json()) as { version?: string }
+  return value.version
+}
+
+async function bunAdd(
+  root: string,
+  names: readonly string[],
+  development = false,
+) {
+  if (!names.length) return
+  const specs = names.map((name) => `${name}@${release.channel}`)
+  const args = ["add", "--exact", ...(development ? ["--dev"] : []), ...specs]
+  const child = Bun.spawn([process.execPath, ...args], {
+    cwd: root,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  const exitCode = await child.exited
+  if (exitCode !== 0) {
+    throw new Error(
+      `Bun could not install ${specs.join(", ")} (exit ${exitCode}).`,
+    )
+  }
+}
+
+export function registerPluginPackages(program: Command) {
+  const plugins = program
+    .command("plugins")
+    .description("manage official @pathmx/* packages")
+
+  plugins
+    .command("list")
+    .description("list installed @pathmx/* packages")
+    .action(async (_options, command: Command) => {
+      const root = projectRoot(command)
+      const installed = installedPlugins(await projectManifest(root))
+      if (!installed.length) {
+        console.log("No @pathmx/* packages are installed.")
+        return
+      }
+      for (const plugin of installed) {
+        const version = await resolvedVersion(root, plugin.name)
+        console.log(
+          `${plugin.name} ${plugin.spec}${version ? ` (${version})` : " (not installed)"}`,
+        )
+      }
+    })
+
+  plugins
+    .command("add")
+    .description(`add packages from the PathMX ${release.channel} channel`)
+    .argument("<plugins...>", "package names, such as react or mermaid")
+    .action(async (inputs: string[], _options, command: Command) => {
+      await projectManifest(projectRoot(command))
+      await bunAdd(projectRoot(command), inputs.map(pluginPackageName))
+    })
+
+  plugins
+    .command("update")
+    .description(
+      `update installed packages from the ${release.channel} channel`,
+    )
+    .argument("[plugins...]", "installed package names; defaults to all")
+    .action(async (inputs: string[], _options, command: Command) => {
+      const root = projectRoot(command)
+      const installed = installedPlugins(await projectManifest(root))
+      const selected = inputs.length
+        ? inputs.map(pluginPackageName)
+        : installed.map(({ name }) => name)
+      const missing = selected.filter(
+        (name) => !installed.some((plugin) => plugin.name === name),
+      )
+      if (missing.length) {
+        throw new Error(
+          `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not installed; use \`pathmx plugins add\` first.`,
+        )
+      }
+      if (!selected.length) {
+        console.log("No @pathmx/* packages are installed.")
+        return
+      }
+      const regular = selected.filter(
+        (name) =>
+          !installed.find((plugin) => plugin.name === name)?.development,
+      )
+      const development = selected.filter(
+        (name) => installed.find((plugin) => plugin.name === name)?.development,
+      )
+      await bunAdd(root, regular)
+      await bunAdd(root, development, true)
+    })
+}

package/cli/plugins.ts

@@ -0,0 +1,95 @@
+import { dirname } from "node:path"
+import type { Command } from "commander"
+import { PluginDatabases } from "../database.ts"
+import { bunEnvironment } from "../environments/bun.ts"
+import { discoverRepositoryPlugins } from "../environments/bun-plugins.ts"
+import { Log } from "../log.ts"
+import { canonicalPluginId } from "../plugins/types.ts"
+import {
+  expandPluginContributions,
+  instantiatePlugin,
+} from "../plugins/preset.ts"
+import { createPluginLog } from "../plugins/context.ts"
+import { createPatternInstaller } from "../pattern.ts"
+import { projectDirectory } from "../project.ts"
+import { resolveRoot } from "./utils.ts"
+
+function optionFromArgv(argv: readonly string[], long: string, short: string) {
+  for (let index = 2; index < argv.length; index++) {
+    const value = argv[index]
+    if (value === long || value === short) return argv[index + 1]
+    if (value?.startsWith(`${long}=`)) return value.slice(long.length + 1)
+  }
+}
+
+function rootsFromArgv(argv: readonly string[]) {
+  const actions = optionFromArgv(argv, "--actions", "-a")
+  return {
+    pathsRoot: resolveRoot(optionFromArgv(argv, "--root", "-r")),
+    actionsRoot: actions ? resolveRoot(actions) : undefined,
+  }
+}
+
+export async function registerPluginCommands(
+  program: Command,
+  argv: readonly string[],
+) {
+  const { pathsRoot, actionsRoot } = rootsFromArgv(argv)
+  const projectRoot = dirname(pathsRoot)
+  const stateRoot = projectDirectory(pathsRoot, ".pathmx/state")
+  const log = new Log({ level: "error" })
+  const contributions = await discoverRepositoryPlugins(pathsRoot, log)
+  const plugins =
+    expandPluginContributions(contributions).map(instantiatePlugin)
+  const databases = new PluginDatabases(bunEnvironment.database, stateRoot)
+  const patterns = createPatternInstaller(bunEnvironment, {
+    paths: pathsRoot,
+    project: projectRoot,
+  })
+  const close = () => databases.close()
+
+  try {
+    for (const plugin of plugins) {
+      if (!plugin.commands) continue
+      canonicalPluginId(plugin.id)
+      if (program.commands.some((command) => command.name() === plugin.id)) {
+        throw new Error(
+          `Plugin command conflicts with core command: ${plugin.id}`,
+        )
+      }
+      if (plugin.database) databases.register(plugin.id, plugin.database)
+      const group = program
+        .command(plugin.id)
+        .description(
+          plugin.name
+            ? `${plugin.name} administration`
+            : `${plugin.id} administration`,
+        )
+      plugin.commands(
+        group,
+        Object.freeze({
+          plugin: plugin.id,
+          pathsRoot,
+          actionsRoot,
+          projectRoot,
+          stateRoot,
+          log: createPluginLog(log, plugin.id),
+          database: databases.get(plugin.id),
+          patterns,
+        }),
+      )
+    }
+  } catch (error) {
+    try {
+      await close()
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        "Plugin command registration failed.",
+      )
+    }
+    throw error
+  }
+
+  return close
+}

package/cli/query.ts

@@ -0,0 +1,225 @@
+import type { Command } from "commander"
+import type { Engine } from "../host/engine.ts"
+import type { QueryRequest, QueryScalar, QuerySort } from "../query/model.ts"
+import { Log } from "../log.ts"
+import { queryRecordValue, type QueryField } from "../query/fields.ts"
+import { createInspectionView } from "../view/session.ts"
+import { fail, loadApp, rootFromCommand } from "./utils.ts"
+
+type QueryFormat = "json" | "jsonl" | "table"
+
+type QueryOptions = Readonly<{
+  as?: string
+  format: QueryFormat
+  from?: string
+  input?: string
+  where: readonly string[]
+  sort: readonly string[]
+  limit?: number
+  type?: string
+  has: readonly string[]
+  recursive?: boolean
+  request?: string
+}>
+
+function collect(value: string, values: string[]) {
+  return [...values, value]
+}
+
+function positiveInteger(value: string) {
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new Error(`Invalid query limit: ${value}`)
+  }
+  return parsed
+}
+
+function formatOption(value: string): QueryFormat {
+  if (value === "json" || value === "jsonl" || value === "table") return value
+  throw new Error(`Unsupported query format: ${value}`)
+}
+
+function scalar(value: string): QueryScalar {
+  const trimmed = value.trim()
+  if (trimmed === "null") return null
+  if (trimmed === "true") return true
+  if (trimmed === "false") return false
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(trimmed)) {
+    const number = Number(trimmed)
+    if (Number.isFinite(number)) return number
+  }
+  if (trimmed.startsWith('"')) {
+    const parsed = JSON.parse(trimmed)
+    if (typeof parsed !== "string") {
+      throw new Error(`Query value is not a scalar string: ${value}`)
+    }
+    return parsed
+  }
+  return value
+}
+
+function whereEntries(entries: readonly string[]) {
+  const where: Record<string, QueryScalar> = {}
+  for (const entry of entries) {
+    const separator = entry.indexOf("=")
+    if (separator <= 0) {
+      throw new Error(`Invalid query filter: ${entry}; expected field=value.`)
+    }
+    const field = entry.slice(0, separator).trim()
+    if (!field) throw new Error(`Invalid query filter: ${entry}`)
+    where[field] = scalar(entry.slice(separator + 1))
+  }
+  return where
+}
+
+function sortEntries(entries: readonly string[]) {
+  return entries.map((entry): QuerySort => {
+    const [field, direction, extra] = entry.split(":")
+    if (!field?.trim() || extra !== undefined) {
+      throw new Error(`Invalid query sort: ${entry}`)
+    }
+    if (direction && direction !== "asc" && direction !== "desc") {
+      throw new Error(`Invalid query sort direction: ${direction}`)
+    }
+    const normalizedDirection =
+      direction === "asc" || direction === "desc" ? direction : undefined
+    return {
+      by: field.trim(),
+      ...(normalizedDirection ? { direction: normalizedDirection } : {}),
+    }
+  })
+}
+
+async function requestFile(app: Engine, path: string) {
+  const text =
+    path === "-"
+      ? await new Response(Bun.stdin.stream()).text()
+      : await Bun.file(path).text()
+  let parsed: unknown
+  if (path.endsWith(".yaml") || path.endsWith(".yml")) {
+    parsed = app.environment.yaml.parse(text)
+  } else {
+    try {
+      parsed = JSON.parse(text)
+    } catch (error) {
+      if (path.endsWith(".json")) throw error
+      parsed = app.environment.yaml.parse(text)
+    }
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Query request must be a JSON or YAML object.")
+  }
+  return parsed as Record<string, unknown>
+}
+
+async function queryRequest(app: Engine, options: QueryOptions) {
+  const request = options.request ? await requestFile(app, options.request) : {}
+  const where = {
+    ...((request.where as Record<string, QueryScalar> | undefined) ?? {}),
+    ...whereEntries(options.where),
+  }
+  const sort = [
+    ...((request.sort as readonly QuerySort[] | undefined) ?? []),
+    ...sortEntries(options.sort),
+  ]
+  return {
+    ...request,
+    ...(options.from !== undefined ? { from: options.from } : {}),
+    ...(options.input !== undefined
+      ? { input: JSON.parse(options.input) }
+      : {}),
+    ...(Object.keys(where).length ? { where } : {}),
+    ...(sort.length ? { sort } : {}),
+    ...(options.limit !== undefined ? { limit: options.limit } : {}),
+    ...(options.type !== undefined ? { type: options.type } : {}),
+    ...(options.has.length ? { has: options.has } : {}),
+    ...(options.recursive === false ? { recursive: false } : {}),
+  } as QueryRequest<unknown>
+}
+
+function cell(value: unknown) {
+  if (value == null) return ""
+  return typeof value === "string" ? value : String(value)
+}
+
+function table(columns: readonly QueryField[], results: readonly unknown[]) {
+  const rows = results.map((result) =>
+    columns.map(({ path }) => cell(queryRecordValue(result, path))),
+  )
+  const headers = columns.map(({ path, label }) => label ?? path)
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)),
+  )
+  return [headers, ...rows]
+    .map((row) =>
+      row
+        .map((value, index) => value.padEnd(widths[index] ?? value.length))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n")
+}
+
+export async function executeQuery(
+  app: Engine,
+  query: string,
+  options: QueryOptions,
+) {
+  const request = await queryRequest(app, options)
+  const actor = options.as ? app.actor(options.as) : undefined
+  if (options.as && !actor) throw new Error(`Actor not found: ${options.as}`)
+  const view = createInspectionView(app, actor)
+  const results = (await app.queries.run(
+    view,
+    query,
+    request,
+  )) as readonly unknown[]
+  if (options.format === "json") return JSON.stringify(results, null, 2)
+  if (options.format === "jsonl") {
+    return results.map((result) => JSON.stringify(result)).join("\n")
+  }
+  const fields = await app.queries.fields(query, request)
+  const columns = fields.filter(({ path }) =>
+    results.some((result) => queryRecordValue(result, path) !== undefined),
+  )
+  return table(columns, results)
+}
+
+export function registerQuery(program: Command) {
+  program
+    .command("query")
+    .description("Query Sources, Blocks, or an installed named query")
+    .argument("<query>", "sources, blocks, or plugin:name")
+    .option("--from <scope>", "canonical or Actor-relative scope")
+    .option("--input <json>", "named-query input as JSON")
+    .option("--where <field=value>", "scalar equality filter", collect, [])
+    .option("--sort <field[:direction]>", "result ordering", collect, [])
+    .option("--limit <number>", "maximum result count", positiveInteger)
+    .option("--type <type>", "built-in Source or Block type")
+    .option("--has <prop>", "required registered data prop", collect, [])
+    .option("--no-recursive", "exclude nested scopes")
+    .option("--as <actor>", "inspect through an Actor's effective access")
+    .option("--request <file>", "JSON/YAML request file, or - for stdin")
+    .option(
+      "--format <format>",
+      "output format: json, jsonl, or table",
+      formatOption,
+      "json",
+    )
+    .action(async (query: string, options: QueryOptions, command: Command) => {
+      let app: Engine | undefined
+      try {
+        const resolved = rootFromCommand(command)
+        app = await loadApp(resolved.root, {
+          actionsRoot: resolved.actionsRoot,
+          buildCache: false,
+          log: new Log({ sink() {} }),
+        })
+        console.log(await executeQuery(app, query, options))
+      } catch (error) {
+        fail(error)
+      } finally {
+        await app?.close()
+      }
+    })
+}