@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/assets/intent/agents-fence.md

@@ -0,0 +1,10 @@
+<!-- intent-skills:start -->
+## Skill Loading
+
+Before editing files for a substantial task:
+- Run `pnpm exec intent list` from the workspace root to see available local skills.
+- If a listed skill matches the task, run `pnpm exec intent load <package>#<skill>` before changing files.
+- Use the loaded `SKILL.md` guidance while making the change.
+- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
+- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
+<!-- intent-skills:end -->

package/assets/intent/intent-claude-gate.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { createHash } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+
+const AGENT = "claude"
+const CATALOG_COMMAND = "pnpm exec intent list --json --no-notices"
+const EDIT_TOOLS = new Set(["Edit","MultiEdit","NotebookEdit","Write"])
+// MESH-2162: name the exact runnable commands, not a vague "follow the setup".
+// An agent that hits this deny WITHOUT the SessionStart catalog in view (subagent,
+// post-compaction, headless) otherwise has no command to run — the "guess a bare
+// `intent`, fail, give up" loop MESH-2160 closed for the catalog. Reuse
+// CATALOG_COMMAND so the listing invocation stays in one place.
+const GATE_DENY_REASON = `Blocked: load matching TanStack guidance before editing. Run \`${CATALOG_COMMAND}\` to see available skills, then \`pnpm exec intent load <package>#<skill>\` for the matching one, then retry the edit. (No bare \`intent\` on PATH — use \`pnpm exec intent\`.)`
+const INTENT_COMMAND_PATTERN = /(?:^|&&|\|\||;|\|)\s*((?:bunx\s+@tanstack\/intent(?:@latest)?)|(?:pnpm\s+exec\s+intent)|(?:pnpm\s+dlx\s+@tanstack\/intent(?:@latest)?)|(?:npx\s+@tanstack\/intent(?:@latest)?)|(?:yarn\s+dlx\s+@tanstack\/intent(?:@latest)?)|(?:intent))\s+(list|load)(?:\s+([^\s|;&]+))?/i
+
+// LOCAL HARDENING (MESH-2020): this file started as `intent install` output, but it
+// is committed and CLI-managed — `mesh skills sync` (and `mesh init app-tenant --fix`)
+// overwrite it from the mesh-cli asset (libs/mesh-cli/assets/intent/intent-claude-gate.mjs
+// in mesh-platform). Never fix one copy without the other; in mesh-platform,
+// scripts/check-intent-hook-sync.mjs fails CI when they diverge. The gate
+// deliberately fails OPEN — it must never block a session or an edit on a bug in
+// the gate tooling itself. But the original blanket `catch {}` made a broken gate
+// SILENT: it would stop enforcing with zero signal. We keep fail-open, but surface
+// the failure on stderr so it's diagnosable.
+try {
+  await main()
+} catch (err) {
+  console.error(
+    `[intent-${AGENT}-gate] hook error — continuing (gate open), but enforcement/catalog may be degraded: ${err?.stack ?? err}`,
+  )
+}
+
+process.exit(0)
+
+async function main() {
+  const event = readEventFromStdin()
+
+  if (isSessionStartEvent(event)) {
+    const additionalContext = await createSessionCatalogContext(rootForEvent(event))
+    if (additionalContext) {
+      process.stdout.write(JSON.stringify(sessionStartOutput(additionalContext)))
+    }
+    return
+  }
+
+  const stateFile = stateFileForEvent(event)
+  const observation = observationFromEvent(event)
+
+  if (observation) {
+    appendObservation(stateFile, observation)
+  }
+
+  const toolName = event?.tool_name ?? event?.toolName
+  if (typeof toolName === 'string' && EDIT_TOOLS.has(toolName) && !hasLoad(stateFile)) {
+    process.stdout.write(JSON.stringify(denyOutput()))
+  }
+}
+
+function readEventFromStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function isSessionStartEvent(event) {
+  return (event?.hook_event_name ?? event?.hookEventName) === 'SessionStart'
+}
+
+function rootForEvent(event) {
+  return typeof event?.cwd === 'string' ? event.cwd : process.cwd()
+}
+
+async function createSessionCatalogContext(root) {
+  try {
+    const start = performance.now()
+    const result = readIntentList(root)
+    const durationMs = performance.now() - start
+    console.error(
+      `[intent-${AGENT}-session-catalog] listIntentSkills found ${result.skills.length} skills from ${result.packages.length} packages in ${formatDuration(durationMs)} (packageJsonReadCount=${result.debug?.scan.packageJsonReadCount ?? 'unknown'})`,
+    )
+    return formatSessionCatalog(result)
+  } catch (err) {
+    // Fail open (no catalog) but visibly — a silent empty catalog looked identical
+    // to "no skills", hiding a broken `intent list` (e.g. version skew, parse error).
+    console.error(
+      `[intent-${AGENT}-session-catalog] failed to load skill catalog, continuing without it: ${err?.message ?? err}`,
+    )
+    return ''
+  }
+}
+
+function readIntentList(root) {
+  const output = execFileSync(CATALOG_COMMAND, {
+    cwd: root,
+    encoding: 'utf8',
+    env: { ...process.env, INTENT_AUDIENCE: 'agent' },
+    maxBuffer: 1024 * 1024,
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 9000,
+  })
+  return JSON.parse(output)
+}
+
+function formatDuration(durationMs) {
+  return `${durationMs.toFixed(1)}ms`
+}
+
+function formatSessionCatalog(result) {
+  if (!Array.isArray(result.skills) || result.skills.length === 0) return ''
+
+  return [
+    'TanStack Intent skills are available in this repository.',
+    '',
+    'Before substantial work, check whether a listed skill matches the task or package you are about to work in. If one clearly matches, load its full guidance BEFORE you reason about that package by running the exact command shown for it below (always `pnpm exec intent load ...` — there is no bare `intent` on PATH, so `intent ...`/`npx intent ...` will fail).',
+    '',
+    'If no skill clearly matches, continue normally. Do not load a skill just to improve phrasing or gather nonessential context.',
+    '',
+    'Available local Intent skills:',
+    formatSkillCatalog(result.skills),
+    formatWarnings(result),
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+function formatSkillCatalog(skills) {
+  // Render each skill as a copy-paste load command (MESH-2160). `skill.use` is the
+  // exact `<package>#<skill>` id, so agents don't have to guess the invocation — the
+  // vague "load with the Intent CLI" wording made them try a non-existent bare
+  // `intent` and give up. LOCAL CUSTOMIZATION: re-apply if you re-run `intent install`.
+  return skills
+    .map((skill) => `- \`pnpm exec intent load ${skill.use}\` — ${normalizeDescription(skill.description)}`)
+    .join('\n')
+}
+
+function normalizeDescription(description) {
+  return typeof description === 'string' ? description.replace(/\s+/g, ' ').trim() : ''
+}
+
+function formatWarnings(result) {
+  const warnings = [
+    ...(Array.isArray(result.warnings) ? result.warnings : []),
+    ...(Array.isArray(result.conflicts)
+      ? result.conflicts.map(
+          (conflict) =>
+            `Version conflict for ${conflict.packageName}; using ${conflict.chosen.version}`,
+        )
+      : []),
+  ]
+
+  if (warnings.length === 0) return ''
+  return `\nWarnings:\n${warnings.map((warning) => `- ${warning}`).join('\n')}`
+}
+
+function sessionStartOutput(additionalContext) {
+  if (AGENT === 'copilot') {
+    return { additionalContext }
+  }
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext,
+    },
+  }
+}
+
+function stateFileForEvent(event) {
+  const sessionId = typeof event?.session_id === 'string' ? event.session_id : 'unknown'
+  const cwd = typeof event?.cwd === 'string' ? event.cwd : process.cwd()
+  const key = createHash('sha256').update(AGENT + '\0' + cwd + '\0' + sessionId).digest('hex')
+  return join(tmpdir(), 'tanstack-intent-hooks', key + '.jsonl')
+}
+
+function observationFromEvent(event) {
+  if (!event || typeof event !== 'object') return undefined
+  const toolName = event.tool_name ?? event.toolName
+  const toolInput = event.tool_input ?? event.toolArgs
+  if (toolName !== 'Bash') return undefined
+  const command = typeof toolInput === 'string' ? safeCommandFromString(toolInput) : commandFromObject(toolInput)
+  const parsed = parseIntentInvocation(command)
+  if (!parsed || typeof command !== 'string') return undefined
+  return { action: parsed.action, skillUse: parsed.skillUse, raw: command }
+}
+
+function parseIntentInvocation(command) {
+  if (typeof command !== 'string') return undefined
+  const match = command.match(INTENT_COMMAND_PATTERN)
+  if (!match?.[1] || !match[2]) return undefined
+  const action = match[2].toLowerCase()
+  if (action !== 'list' && action !== 'load') return undefined
+  const skillUse = action === 'load' ? match[3] : undefined
+  if (action === 'load' && !skillUse) return undefined
+  return action === 'load' ? { action, skillUse } : { action }
+}
+
+function commandFromObject(value) {
+  return value && typeof value === 'object' ? value.command : undefined
+}
+
+function safeCommandFromString(value) {
+  try {
+    const command = commandFromObject(JSON.parse(value))
+    return typeof command === 'string' ? command : value
+  } catch {
+    return value
+  }
+}
+
+function appendObservation(stateFile, observation) {
+  try {
+    mkdirSync(dirname(stateFile), { recursive: true })
+    appendFileSync(stateFile, JSON.stringify({ ts: new Date().toISOString(), ...observation }) + '\n')
+  } catch {
+  }
+}
+
+function hasLoad(stateFile) {
+  if (!existsSync(stateFile)) return false
+  try {
+    return readFileSync(stateFile, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .some((line) => {
+        try {
+          return JSON.parse(line).action === 'load'
+        } catch {
+          return false
+        }
+      })
+  } catch {
+    return false
+  }
+}
+
+function denyOutput() {
+  if (AGENT === 'copilot') {
+    return { permissionDecision: 'deny', permissionDecisionReason: GATE_DENY_REASON }
+  }
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: GATE_DENY_REASON,
+    },
+  }
+}

package/assets/log-shipper.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * mesh dev --local log shipper.
+ *
+ * Sits at the end of each service's launch pipeline:
+ *   { <dev command>; } 2>&1 | node log-shipper.mjs
+ *
+ * - Echoes every byte to stderr untouched (the tmux pane keeps colors).
+ * - Ships ANSI-stripped lines to the local platform's OTel collector via
+ *   OTLP/HTTP — the SAME ingestion path instrumented apps use, carrying the
+ *   resource attributes `mesh dev` injects (OTEL_RESOURCE_ATTRIBUTES /
+ *   OTEL_SERVICE_NAME), so Loki indexes k8s_namespace_name /
+ *   k8s_deployment_name exactly like the in-cluster k8sattributes processor.
+ *
+ * Why not a log file tailed by the collector: host-written files cross the
+ * macOS Docker mount with stale attributes — appends can stay invisible to
+ * the in-container tailer indefinitely. OTLP over localhost has no such
+ * boundary. Shipping is best-effort: the collector being down never breaks
+ * the dev loop.
+ */
+
+const ENDPOINT = (process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318").replace(/\/+$/, "");
+const FLUSH_MS = 1000;
+const MAX_BATCH = 200;
+
+const attributes = [];
+for (const pair of (process.env.OTEL_RESOURCE_ATTRIBUTES ?? "").split(",")) {
+  const eq = pair.indexOf("=");
+  if (eq > 0) {
+    attributes.push({ key: pair.slice(0, eq).trim(), value: { stringValue: pair.slice(eq + 1).trim() } });
+  }
+}
+if (process.env.OTEL_SERVICE_NAME) {
+  attributes.push({ key: "service.name", value: { stringValue: process.env.OTEL_SERVICE_NAME } });
+}
+
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b[=>]|\r/g;
+
+let queue = [];
+let flushTimer = null;
+let flushing = Promise.resolve();
+
+function enqueue(line) {
+  const clean = line.replace(ANSI, "");
+  if (!clean.trim()) return;
+  queue.push({ timeUnixNano: String(Date.now()) + "000000", body: { stringValue: clean } });
+  if (queue.length >= MAX_BATCH) flush();
+  else if (!flushTimer) flushTimer = setTimeout(flush, FLUSH_MS);
+}
+
+function flush() {
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  if (queue.length === 0) return flushing;
+  const logRecords = queue;
+  queue = [];
+  const payload = JSON.stringify({
+    resourceLogs: [
+      {
+        resource: { attributes },
+        scopeLogs: [{ scope: { name: "mesh-dev-local" }, logRecords }],
+      },
+    ],
+  });
+  flushing = fetch(`${ENDPOINT}/v1/logs`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: payload,
+    signal: AbortSignal.timeout(5000),
+  }).catch(() => {
+    /* best-effort — never break the dev loop */
+  });
+  return flushing;
+}
+
+let buffer = "";
+process.stdin.on("data", (chunk) => {
+  process.stderr.write(chunk); // raw passthrough → the tmux pane
+  buffer += chunk.toString("utf-8");
+  let newline;
+  while ((newline = buffer.indexOf("\n")) >= 0) {
+    enqueue(buffer.slice(0, newline));
+    buffer = buffer.slice(newline + 1);
+  }
+});
+
+process.stdin.on("end", async () => {
+  if (buffer) enqueue(buffer);
+  await flush();
+  await flushing;
+  process.exit(0);
+});

package/bin/mesh.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * mesh dev launcher (MESH-2261).
+ *
+ * In the monorepo this IS the package `bin`, and it ALWAYS runs the CLI from
+ * TypeScript source via tsx — so the CLI is never stale, needs no build, and
+ * `pnpm exec mesh` works even in a never-built worktree.
+ *
+ * There is NO source-vs-dist detection here: the swap is native and
+ * build-time. `scripts/build-for-publish.ts` rewrites the PUBLISHED package's
+ * `bin` to `./dist/bin/mesh.js` (mirroring how it rewrites `exports` from
+ * source→dist), so consumers run the built dist and never touch this launcher.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * Node argv that runs the TypeScript entry under tsx with the workspace
+ * `source` export condition. Pure, so it can be unit-tested without spawning.
+ *
+ * `tsxImport` is an ABSOLUTE tsx loader specifier resolved relative to THIS
+ * launcher — not the bare `"tsx"`. A bare `--import tsx` resolves tsx from the
+ * process CWD, so running the launcher from a directory without tsx on its
+ * module path (e.g. `~`) fails with "Cannot find package 'tsx'". Resolving it
+ * against the launcher makes `mesh` work from any cwd.
+ *
+ * @param {string} tsxImport absolute tsx loader (file: URL or path)
+ * @param {string} srcEntry  absolute path to `bin/mesh.ts`
+ * @param {string[]} args    CLI args (process.argv.slice(2))
+ */
+export function sourceRunArgv(tsxImport, srcEntry, args) {
+  return ["--import", tsxImport, "--conditions", "source", srcEntry, ...args];
+}
+
+/** Absolute tsx loader specifier, resolved relative to this launcher. */
+function tsxImportSpecifier() {
+  return pathToFileURL(createRequire(import.meta.url).resolve("tsx")).href;
+}
+
+// Run only when invoked directly (not when imported by a test). Compare
+// REALPATHS: pnpm's `.bin/mesh` shim execs this via a symlinked path, so
+// `process.argv[1]` (symlink) would never string-equal `import.meta.url`
+// (realpath) — collapse both through realpath first.
+function invokedDirectly() {
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1] ?? "");
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  const srcEntry = resolve(dirname(fileURLToPath(import.meta.url)), "mesh.ts");
+  let tsxImport;
+  try {
+    tsxImport = tsxImportSpecifier();
+  } catch {
+    process.stderr.write(
+      "mesh: could not resolve tsx. Run `pnpm install` in this workspace, then retry.\n",
+    );
+    process.exit(1);
+  }
+  try {
+    execFileSync(process.execPath, sourceRunArgv(tsxImport, srcEntry, process.argv.slice(2)), {
+      stdio: "inherit",
+    });
+  } catch (err) {
+    if (err?.signal) {
+      // The CLI died from a signal (e.g. SIGINT) → re-raise it so the exit code
+      // reflects the signal (130 on Ctrl-C) instead of a bare 1.
+      process.kill(process.pid, err.signal);
+    } else {
+      // Exited non-zero → propagate its code; spawn failure → 1.
+      process.exit(typeof err?.status === "number" ? err.status : 1);
+    }
+  }
+}

package/dist/bin/mesh.d.ts

@@ -2,15 +2,13 @@
 /**
  * mesh - CLI for Mesh Lab development utilities
  *
- * Commands:
- *   mesh create-app     Scaffold a new tenant application
- *   mesh dev            Start DB tunnel and run sst dev
- *   mesh tunnel         Start SSM tunnel to platform services
- *   mesh db connect     Start DB tunnel for manual access
- *   mesh db credentials Print database credentials
- *   mesh db env         Export DATABASE_URL for shell
- *   mesh db psql        Connect to database with psql
- *   mesh secrets exec   Run command with secrets as env vars
+ * The command tree itself lives in `src/program.ts` so `mesh docs
+ * cli-reference` can walk it without running the CLI. This file is only the
+ * runner: resolve the version, build the program, parse.
+ *
+ * For the command list, run `mesh --help` or read the generated reference
+ * (`docs/portal/generated/cli-reference.md`) — a hand-maintained list in this
+ * header is exactly the kind of prose that goes stale.
  */
 export {};
 //# sourceMappingURL=mesh.d.ts.map

package/dist/bin/mesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../../bin/mesh.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}
+{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../../bin/mesh.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}