@procedures/lib 0.0.0-stage → 0.2.0

package/dist/workspace.js

@@ -0,0 +1,98 @@
+/**
+ * Workspace helpers
+ *
+ * The client packages live in one pnpm workspace (the client monorepo). These helpers
+ * find the workspace root and decide which dependencies link two ecosystem packages,
+ * so the lib.* procedures work on the monorepo instead of one git repository per package.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMark1Russell7Ref } from "./git/index.js";
+/**
+ * Expand a leading `~/` to the home directory
+ */
+export function expandHome(p) {
+    if (p === "~") {
+        return homedir();
+    }
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+/**
+ * Find the nearest folder at or above `start` that holds pnpm-workspace.yaml
+ */
+export function findWorkspaceRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Resolve the workspace root for a procedure call: the explicit `rootPath` if given,
+ * else the workspace that contains this package.
+ */
+export function resolveWorkspaceRoot(rootPath) {
+    if (rootPath) {
+        // Only a real workspace root: lib.new runs that workspace's cue CLI, and lib.rename rewrites
+        // its files, so a rootPath elsewhere ran a script from any folder (deep dive DATA-18)
+        const root = resolve(expandHome(rootPath));
+        if (!existsSync(join(root, "pnpm-workspace.yaml"))) {
+            throw new Error(`Not a workspace root (no pnpm-workspace.yaml): ${root}`);
+        }
+        return root;
+    }
+    const own = findWorkspaceRoot(dirname(fileURLToPath(import.meta.url)));
+    if (!own) {
+        throw new Error("Could not find the workspace root (no pnpm-workspace.yaml above client-lib). Pass rootPath.");
+    }
+    return own;
+}
+/**
+ * The folder that holds the workspace packages
+ */
+export function packagesDir(root) {
+    return join(root, "packages");
+}
+/**
+ * Return true if a dependency spec links to another ecosystem package:
+ * a workspace link (`workspace:*`) or a `github:mark1russell7/...` reference.
+ */
+export function isEcosystemDependencySpec(spec) {
+    return spec.startsWith("workspace:") || isMark1Russell7Ref(spec);
+}
+/**
+ * The npm scopes of the ecosystem: `@procedures` for the packages of this workspace, and
+ * `@mark1russell7` for the general packages (cue, splay, docker-sqlite and the others).
+ */
+export const ECOSYSTEM_SCOPES = ["@procedures/", "@mark1russell7/"];
+/** True for the name of a package of the ecosystem scopes. */
+export function isEcosystemPackageName(name) {
+    return ECOSYSTEM_SCOPES.some((scope) => name.startsWith(scope));
+}
+/**
+ * Collect the names of the ecosystem packages (`@procedures/*` and `@mark1russell7/*`) that a
+ * package.json depends on (dependencies, devDependencies and peerDependencies), without duplicates.
+ */
+export function extractEcosystemDeps(pkg) {
+    const names = new Set();
+    for (const deps of [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies]) {
+        for (const [name, spec] of Object.entries(deps ?? {})) {
+            if (isEcosystemPackageName(name) && isEcosystemDependencySpec(spec)) {
+                names.add(name);
+            }
+        }
+    }
+    return [...names];
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,90 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/lib",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Workspace procedures for pnpm monorepos: scan the packages, scaffold a new package, audit packages against a template, rename across the workspace, and program runners.",
+  "keywords": [
+    "monorepo",
+    "pnpm",
+    "workspace",
+    "scaffold",
+    "audit",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-lib"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    },
+    "./cli-flags": {
+      "types": "./dist/cli-flags.d.ts",
+      "import": "./dist/cli-flags.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0",
+    "@procedures/dag": "0.2.0",
+    "@procedures/fs": "0.2.0",
+    "@procedures/git": "0.2.0",
+    "@procedures/pnpm": "0.2.0",
+    "@procedures/shell": "0.2.0",
+    "ts-morph": "^24.0.0",
+    "zod": "^4.6.5"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
 }

package/src/cli-flags.ts

@@ -0,0 +1,49 @@
+/**
+ * The global flags of the `mark` CLI.
+ *
+ * `mark` reads a global flag before the command path. After the path, a flag is global only when
+ * the procedure does not declare a flag of that name: `mark docker compose down -v` gives `-v` to
+ * the procedure. `lib.audit` reports each procedure flag that hides a global flag in this way.
+ *
+ * This module has no side effects: `mark` imports it before it loads the procedures.
+ */
+
+export interface CliGlobalFlag {
+  /** The long name, without "--" */
+  readonly long: string;
+  /** The short letter, without "-" */
+  readonly short?: string;
+  /** True when the flag takes a value */
+  readonly takesValue: boolean;
+  /** True when the flag starts a mode (the server or the REPL) and takes no command */
+  readonly mode?: boolean;
+  /** True when the flag is an option of `--server` */
+  readonly serverOption?: boolean;
+  /** The help text */
+  readonly description: string;
+}
+
+export const CLI_GLOBAL_FLAGS: readonly CliGlobalFlag[] = [
+  { long: "help", short: "h", takesValue: false, description: "Show the help" },
+  { long: "version", short: "v", takesValue: false, description: "Show the version" },
+  { long: "verbose", short: "V", takesValue: false, description: "Show more output" },
+  { long: "format", short: "f", takesValue: true, description: "The output format: text, json, table or streaming" },
+  { long: "local", takesValue: false, description: "Run the command in this process, not on the CLI server" },
+  { long: "json", takesValue: true, description: "Run a procedure reference that is given as JSON" },
+  { long: "no-input", takesValue: false, description: "Never ask for a missing argument (also when CI is set)" },
+  { long: "interactive", short: "i", takesValue: false, mode: true, description: "Start the REPL" },
+  { long: "server", takesValue: false, mode: true, description: "Start the CLI server" },
+  { long: "port", takesValue: true, serverOption: true, description: "The port of the CLI server (with --server)" },
+  { long: "host", takesValue: true, serverOption: true, description: "The host of the CLI server (with --server)" },
+  {
+    long: "transport",
+    takesValue: true,
+    serverOption: true,
+    description: "The transport of the CLI server: http, websocket or both (with --server)",
+  },
+];
+
+/** The global flag with this long name or short letter */
+export function findGlobalFlag(name: string, short: boolean): CliGlobalFlag | undefined {
+  return CLI_GLOBAL_FLAGS.find((flag) => (short ? flag.short === name : flag.long === name));
+}

package/src/dag/builder.ts

@@ -0,0 +1,44 @@
+/**
+ * DAG Builder
+ *
+ * Builds the ecosystem-specific dependency DAG from package scan results. This is the only
+ * domain-specific piece; the generic DAG algorithms (buildLeveledDAG, executeDAG, filterDAGFromRoot,
+ * getAncestors, getDescendants, ...) live in @procedures/dag. This package previously
+ * vendored a verbatim copy of those — see documentation/BUGS-2026-07.md (DAG de-dup).
+ */
+
+import type { DAGNode, PackageInfo } from "../types.js";
+
+/**
+ * Build DAG nodes from package info.
+ *
+ * Creates nodes only for packages that are mark1russell7 dependencies and exist in the scanned
+ * packages. `id` mirrors `name` so the nodes satisfy client-dag's DAGNode contract (which keys by
+ * id) while the ecosystem code keeps using the readable `name`.
+ */
+export function buildDAGNodes(
+  packages: Record<string, PackageInfo>
+): Map<string, DAGNode> {
+  const nodes = new Map<string, DAGNode>();
+
+  for (const [name, info] of Object.entries(packages)) {
+    // Only include packages that have mark1russell7 dependencies or are dependencies of others.
+    const deps = info.mark1russell7Deps.filter((dep) => packages[dep] !== undefined);
+
+    const gitRef = info.gitRemote ?? `github:mark1russell7/${info.name}#${info.currentBranch ?? "main"}`;
+    const requiredBranch = info.currentBranch ?? "main";
+
+    const node: DAGNode = {
+      id: name,
+      name,
+      repoPath: info.repoPath,
+      gitRef,
+      requiredBranch,
+      dependencies: deps,
+    };
+
+    nodes.set(name, node);
+  }
+
+  return nodes;
+}

package/src/dag/index.ts

@@ -0,0 +1,23 @@
+/**
+ * DAG utilities.
+ *
+ * The generic DAG algorithms are re-exported from @procedures/dag; only buildDAGNodes
+ * (which builds the ecosystem package graph) is domain-specific and stays local. This package
+ * previously vendored a verbatim copy of the generic algorithms — deduplicated here. The nodes
+ * carry an `id` (mirroring `name`) so they satisfy client-dag's generic `DAGNode` contract.
+ * See documentation/BUGS-2026-07.md (DAG de-dup / H27).
+ */
+
+export {
+  buildLeveledDAG,
+  getTopologicalOrder,
+  visualizeDAG,
+  executeDAG,
+  executeDAGSequential,
+  createProcessor,
+  filterDAGFromRoot,
+  getAncestors,
+  getDescendants,
+} from "@procedures/dag";
+
+export { buildDAGNodes } from "./builder.js";

package/src/git/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Git utilities
+ */
+
+export {
+  parseGitRef,
+  isGitRef,
+  isMark1Russell7Ref,
+  extractMark1Russell7Deps,
+  getPackageNameFromRef,
+} from "./ref-parser.js";

package/src/git/ref-parser.ts

@@ -0,0 +1,83 @@
+/**
+ * Git reference parser
+ *
+ * Parses git references from package.json dependencies like:
+ * - github:mark1russell7/logger#main
+ * - github:mark1russell7/client#v1.0.0
+ */
+
+import type { GitRef } from "../types.js";
+
+/**
+ * Parse a git reference string into its components
+ *
+ * @example
+ * parseGitRef("github:mark1russell7/logger#main")
+ * // { raw: "...", host: "github", owner: "mark1russell7", repo: "logger", ref: "main" }
+ */
+export function parseGitRef(refString: string): GitRef | null {
+  // Pattern: host:owner/repo#ref
+  // Examples:
+  //   github:mark1russell7/logger#main
+  //   gitlab:user/project#develop
+  const match = refString.match(/^(\w+):([^/]+)\/([^#]+)#(.+)$/);
+
+  if (!match) {
+    return null;
+  }
+
+  const [, host, owner, repo, ref] = match;
+
+  return {
+    raw: refString,
+    host: host!,
+    owner: owner!,
+    repo: repo!,
+    ref: ref!,
+  };
+}
+
+/**
+ * Check if a dependency string is a git reference
+ */
+export function isGitRef(dep: string): boolean {
+  return /^\w+:[^/]+\/[^#]+#.+$/.test(dep);
+}
+
+/**
+ * Check if a dependency is a mark1russell7 git reference
+ */
+export function isMark1Russell7Ref(dep: string): boolean {
+  return dep.includes("mark1russell7/");
+}
+
+/**
+ * Extract mark1russell7 git refs from package.json dependencies
+ */
+export function extractMark1Russell7Deps(
+  dependencies: Record<string, string>
+): GitRef[] {
+  const refs: GitRef[] = [];
+
+  for (const [, version] of Object.entries(dependencies)) {
+    if (isMark1Russell7Ref(version)) {
+      const ref = parseGitRef(version);
+      if (ref) {
+        refs.push(ref);
+      }
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Get the package name from a git ref
+ * Uses the repo name, optionally scoped with @mark1russell7/
+ */
+export function getPackageNameFromRef(ref: GitRef): string {
+  // For mark1russell7 repos, the package name is usually @mark1russell7/{repo}
+  // But some packages like "client" are unscoped
+  // We'll need to check the actual package.json to be sure
+  return ref.repo;
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @procedures/lib
+ *
+ * Library management procedures for the workspace - scan, new, audit, rename.
+ */
+
+export * from "./module.js";
+
+// Re-export types
+export * from "./types.js";
+
+// Re-export procedures
+export {
+  libScan,
+  libRename,
+  libNew,
+  libAudit,
+} from "./procedures/lib/index.js";
+
+// Re-export ecosystem procedures
+export {
+  ecosystemProcedures,
+  EcosystemProceduresInputSchema,
+} from "./procedures/ecosystem/index.js";
+export type {
+  EcosystemProceduresInput,
+  EcosystemProceduresOutput,
+  ProcedureInfo,
+  PackageProcedures,
+} from "./procedures/ecosystem/index.js";
+
+// Re-export DAG utilities (ecosystem-specific)
+export {
+  buildDAGNodes,
+  filterDAGFromRoot,
+  getAncestors,
+  getDescendants,
+  buildLeveledDAG,
+  getTopologicalOrder,
+  visualizeDAG,
+  executeDAG,
+  executeDAGSequential,
+  createProcessor,
+} from "./dag/index.js";
+
+// Re-export git utilities
+export {
+  parseGitRef,
+  isGitRef,
+  isMark1Russell7Ref,
+  extractMark1Russell7Deps,
+  getPackageNameFromRef,
+} from "./git/index.js";
+
+// The global flags of the mark CLI (also at "@procedures/lib/cli-flags", with no side effects)
+export { CLI_GLOBAL_FLAGS, findGlobalFlag, type CliGlobalFlag } from "./cli-flags.js";