@tgcloud/cli 0.1.0

package/src/core/migration-flow.js

@@ -0,0 +1,356 @@
+import chalk from 'chalk';
+import { confirm, askLetter, waitForEnter, EOF } from '../utils/prompt.js';
+import { createSpinner } from '../utils/spinner.js';
+import { applyMigration } from '../api/endpoints.js';
+import {
+  formatBriefSummary,
+  formatChange,
+  changeId,
+  kindLabel,
+} from './db-changes.js';
+import { ROOT_FILE } from './project-layout.js';
+
+/**
+ * Linear walk-through migration. Used by `migrate`. (`push` only prints
+ * the brief summary and suggests `tgcloud migrate`.)
+ *
+ * Flow (interactive):
+ *   1. Brief summary (one line per change).
+ *   2. "Proceed with migration?" prompt — always asked.
+ *   3. Walk through actionable changes with [N/M] step counter:
+ *      - Safe changes: one grouped step (a single step when there's just one),
+ *        applied or skipped as a whole. Prompt [y]es/[n]o/[q]uit.
+ *      - Warning: each as own step, [y]es/[n]o/[q]uit.
+ *      - Manual / Undocumented: NOT counted as steps. Shown as a tail
+ *        block after all decisions, with collective explanation +
+ *        "Press Enter to continue...".
+ *   4. Final summary line.
+ *
+ * Flags:
+ *   --yes      auto-yes everywhere (safe batch + every warning).
+ *   --safe     auto-yes for safe batch, auto-no for every warning.
+ *   --dry-run  show summary + all cards, no prompts, no apply.
+ *
+ * @param {string} token
+ * @param {Array}  dbChanges
+ * @param {object} options
+ * @returns {Promise<{applied:number, skipped:number, failed:number}|undefined>}
+ *   Apply tally (undefined for dry-run / empty). Callers use `failed` to set
+ *   the process exit code.
+ */
+export async function runMigrationFlow(token, dbChanges, options = {}) {
+  if (!dbChanges?.length) return;
+
+  const good    = dbChanges.filter((c) => c.status === 'good');
+  const warning = dbChanges.filter((c) => c.status === 'warning');
+  const manual  = dbChanges.filter((c) => c.status === 'manual');
+  const undoc   = dbChanges.filter((c) => c.status === 'undocumented');
+
+  printBriefHeader(dbChanges);
+
+  if (options.dryRun) return runDryRun(dbChanges);
+  if (options.yes || options.safe) return runCI(token, { good, warning, manual, undoc }, options);
+
+  return runInteractive(token, { good, warning, manual, undoc }, options);
+}
+
+// ─── Brief header ──────────────────────────────────────────────────────────
+
+function printBriefHeader(dbChanges) {
+  const n = dbChanges.length;
+  console.log('');
+  console.log(chalk.bold(`Schema out of sync — ${n} change${n === 1 ? '' : 's'}:`));
+  console.log(formatBriefSummary(dbChanges));
+  console.log('');
+}
+
+// ─── Dry run ───────────────────────────────────────────────────────────────
+
+function runDryRun(dbChanges) {
+  for (const c of dbChanges) {
+    console.log(formatChange(c));
+    console.log('');
+  }
+  console.log(chalk.dim('(dry-run — nothing was applied)'));
+}
+
+// ─── Interactive walk-through ──────────────────────────────────────────────
+
+async function runInteractive(token, groups, options) {
+  const { good, warning, manual, undoc } = groups;
+
+  const proceed = await confirm('Proceed with migration?');
+  if (!proceed) {
+    console.log('\nCancelled.');
+    return { applied: 0, skipped: 0, failed: 0 };
+  }
+
+  const stats = { applied: 0, skipped: 0, failed: 0 };
+  // Total step count:
+  //   safe-group   = 1 step (if any)
+  //   each warning = 1 step
+  //   manual       = 1 step (all manual cards shown together — no per-card
+  //                  decision, so spreading them across steps is just noise)
+  //   undoc        = 1 step (same reasoning)
+  const state = {
+    idx: 0,
+    total:
+      (good.length > 0 ? 1 : 0) +
+      warning.length +
+      (manual.length > 0 ? 1 : 0) +
+      (undoc.length > 0 ? 1 : 0),
+    quit: false,
+  };
+
+  // ── Safe ──
+  if (good.length === 1) {
+    await stepSingle(token, good[0], state, stats, options);
+  } else if (good.length > 1) {
+    await stepSafeGroup(token, good, state, stats, options);
+  }
+
+  // ── Warning ──
+  if (!state.quit) {
+    for (let i = 0; i < warning.length; i++) {
+      await stepSingle(token, warning[i], state, stats, options);
+      if (state.quit) {
+        stats.skipped += warning.length - i - 1;
+        break;
+      }
+    }
+  } else {
+    stats.skipped += warning.length;
+  }
+
+  // ── Manual & Undoc — each kind is one combined step ──
+  if (!state.quit) {
+    if (manual.length) await stepInfoGroup(manual, 'manual', state);
+    if (undoc.length)  await stepInfoGroup(undoc,  'undocumented', state);
+  }
+
+  printSummary(stats, { manual: manual.length, undoc: undoc.length, quit: state.quit });
+  return stats;
+}
+
+/**
+ * Informational step covering all changes of a single non-actionable kind
+ * (manual or undocumented). Prints all cards stacked, then one collective
+ * hint, then waits for Enter. No apply.
+ */
+async function stepInfoGroup(changes, kind, state) {
+  state.idx++;
+  for (const c of changes) {
+    console.log(formatChange(c));
+    console.log('');
+  }
+
+  const n = changes.length;
+  const body = kind === 'manual'
+    ? (n === 1
+        ? 'This change must be applied to the database manually.'
+        : `These ${n} changes must be applied to the database manually.`)
+    : (n === 1
+        ? `Not in schema. Update ${ROOT_FILE}, or mark as deprecated to remove.`
+        : `${n} elements exist in the database but not in the schema.\n  Update ${ROOT_FILE} to match, or mark them as deprecated to remove.`);
+  console.log(chalk.blue('Note: ') + body);
+  console.log('');
+
+  await waitForEnter(`[${state.idx}/${state.total}] Press Enter to continue...`);
+}
+
+/**
+ * Step that's a single change card (safe-1 or any warning). Prints the card
+ * and asks Apply? [y]/[n]/[q].
+ */
+async function stepSingle(token, change, state, stats, options) {
+  state.idx++;
+  console.log(formatChange(change));
+  console.log('');
+
+  const choice = await askLetter(`[${state.idx}/${state.total}] Apply?`, [
+    { key: 'y', label: 'yes' },
+    { key: 'n', label: 'no' },
+    { key: 'q', label: 'quit' },
+  ]);
+
+  if (choice === 'q' || choice === EOF) {
+    state.quit = true;
+    stats.skipped++;
+    console.log(chalk.dim('  ⊘ skipped (quit)'));
+    return;
+  }
+  if (choice === 'n') {
+    stats.skipped++;
+    console.log(chalk.dim('  ⊘ skipped'));
+    return;
+  }
+  // 'y'
+  const ok = await applyOne(token, change, options.schema);
+  if (ok) stats.applied++;
+  else    stats.failed++;
+}
+
+/**
+ * Step that's a group of safe changes. Prints all cards, then a single
+ * group prompt — applies (or skips) the whole group atomically. To apply only
+ * some, cancel and edit the schema.
+ */
+async function stepSafeGroup(token, group, state, stats, options) {
+  state.idx++;
+  for (const c of group) {
+    console.log(formatChange(c));
+    console.log('');
+  }
+
+  const choice = await askLetter(
+    `[${state.idx}/${state.total}] Apply these ${group.length} changes?`,
+    [
+      { key: 'y', label: 'yes' },
+      { key: 'n', label: 'no' },
+      { key: 'q', label: 'quit' },
+    ]
+  );
+
+  if (choice === 'q' || choice === EOF) {
+    state.quit = true;
+    stats.skipped += group.length;
+    console.log(chalk.dim(`  ⊘ skipped ${group.length} (quit)`));
+    return;
+  }
+  if (choice === 'n') {
+    stats.skipped += group.length;
+    console.log(chalk.dim(`  ⊘ skipped ${group.length}`));
+    return;
+  }
+  // 'y'
+  const ok = await applyBatch(token, group, options.schema);
+  if (ok) stats.applied += group.length;
+  else    stats.failed  += group.length;
+}
+
+// ─── Summary ───────────────────────────────────────────────────────────────
+
+function printSummary(stats, { manual, undoc, quit }) {
+  console.log('');
+
+  // All counters use `label: N` separated by commas, so the line stays
+  // visually consistent (not a mix of `, ` and `: `).
+  const parts = [
+    `applied: ${stats.applied}`,
+    `skipped: ${stats.skipped}`,
+  ];
+  if (stats.failed) parts.push(`failed: ${stats.failed}`);
+  if (manual)       parts.push(`awaiting manual fix: ${manual}`);
+  if (undoc)        parts.push(`not in schema: ${undoc}`);
+
+  // Capitalize first counter so the sentence reads naturally after the prefix.
+  parts[0] = parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+
+  const nothingActed =
+    stats.applied === 0 && stats.skipped === 0 && stats.failed === 0;
+  const prefix = quit
+    ? 'Migration interrupted.'
+    : nothingActed
+      ? 'Migration finished.'
+      : 'Migration complete.';
+
+  console.log(chalk.bold(`${prefix} ${parts.join(', ')}.`));
+}
+
+// ─── CI mode (--yes / --safe) ──────────────────────────────────────────────
+
+async function runCI(token, groups, options) {
+  const { good, warning, manual, undoc } = groups;
+  const stats = { applied: 0, skipped: 0, failed: 0 };
+
+  // Safe — always attempted in CI (both --yes and --safe).
+  if (good.length) {
+    for (const c of good) {
+      console.log(formatChange(c));
+      console.log('');
+    }
+    const ok = await applyBatch(token, good, options.schema);
+    if (ok) stats.applied += good.length;
+    else    stats.failed  += good.length;
+    console.log('');
+  }
+
+  // Warning — applied only with --yes; --safe shows + skips.
+  for (const c of warning) {
+    console.log(formatChange(c));
+    console.log('');
+    if (options.yes) {
+      const ok = await applyOne(token, c, options.schema);
+      if (ok) stats.applied++;
+      else    stats.failed++;
+    } else {
+      console.log(chalk.dim('  ⊘ skipped (--safe)'));
+      stats.skipped++;
+    }
+    console.log('');
+  }
+
+  // Manual / undoc — show each with its hint, no waitForEnter in CI.
+  for (const c of manual) {
+    console.log(formatChange(c));
+    console.log('');
+    console.log(chalk.blue('Note: ') + 'This change must be applied to the database manually.');
+    console.log('');
+  }
+  for (const c of undoc) {
+    console.log(formatChange(c));
+    console.log('');
+    console.log(chalk.blue('Note: ') + `Not in schema. Update ${ROOT_FILE}, or mark as deprecated to remove.`);
+    console.log('');
+  }
+
+  printSummary(stats, { manual: manual.length, undoc: undoc.length, quit: false });
+  return stats;
+}
+
+// ─── API helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Apply a batch of changes in one POST. Prints inline ✓ per change on success.
+ */
+async function applyBatch(token, changes, schema) {
+  const ids = changes.map(changeId);
+  const spinner = createSpinner(`Applying ${ids.length} change${ids.length === 1 ? '' : 's'}...`);
+  spinner.start();
+  try {
+    await applyMigration(token, { apply: ids, schema });
+    spinner.stop();
+    for (const c of changes) {
+      console.log(chalk.green(`  ✓ ${headerTargetFor(c)}`));
+    }
+    return true;
+  } catch (err) {
+    spinner.stop();
+    console.error(chalk.red('Error: ') + `Batch failed: ${err.message}`);
+    return false;
+  }
+}
+
+async function applyOne(token, change, schema) {
+  const id = changeId(change);
+  const target = headerTargetFor(change);
+  const label = kindLabel(change);
+  const spinner = createSpinner(`Applying ${label} '${target}'...`);
+  spinner.start();
+  try {
+    await applyMigration(token, { apply: [id], schema });
+    spinner.stop();
+    console.log(chalk.green(`  ✓ ${target}`));
+    return true;
+  } catch (err) {
+    spinner.stop();
+    console.error(chalk.red('Error: ') + `${label} '${target}': ${err.message}`);
+    return false;
+  }
+}
+
+function headerTargetFor(change) {
+  if (change.column) return `${change.table}.${change.column}`;
+  if (change.index)  return `${change.table}.${change.index}`;
+  return change.table;
+}

package/src/core/project-layout.js

@@ -0,0 +1,294 @@
+import { loadCachedCapabilities } from './state.js';
+
+/**
+ * Single source of truth for the SHAPE of a tgcloud project: the root file(s),
+ * the module directories and their rules (nested / runnable / synced), plus the
+ * scaffold list and the template contents used by `init`.
+ *
+ * The shape comes from two layers, merged per-aspect:
+ *   1. BASELINE — built into the CLI, used offline and as the fallback.
+ *   2. The server descriptor (GET /capabilities), cached in
+ *      .tgcloud/capabilities.json and refreshed on online commands by
+ *      core/capabilities.js. When present and valid, its fields are authoritative.
+ *
+ * Scaffolding is PATH-DRIVEN: `scaffold` is the full list of files/dirs to
+ * create (files may be nested paths — `docs/x.md`, `handlers/message.js`), and
+ * `templates` is a map keyed by that same relative path → file content. The CLI
+ * holds no hard-coded list of which files exist; the platform can add a file
+ * (a new starter module or doc) by putting it in `scaffold` + `templates`
+ * WITHOUT a CLI release.
+ *
+ * scanner / run / init / deploy derive their behavior from the accessors below
+ * so that discovery, the deploy manifest, the run whitelist, and scaffolding all
+ * move together.
+ */
+
+// Highest project_schema_version this CLI understands. A descriptor with a
+// higher version is still consumed for the parts that parse, but the user is
+// warned (in core/capabilities.js) that newer features may be ignored. Scaffolding
+// is path-driven: `templates` is keyed by relative path and `scaffold` entries may
+// be nested. Template keys that aren't valid relative paths are ignored, and the
+// bundled copy is used instead.
+export const SUPPORTED_SCHEMA_VERSION = 1;
+
+export const BASELINE = {
+  rootFiles: [
+    { name: 'schema.js', singleton: true },
+  ],
+  directories: [
+    { name: 'lib', nested: true, synced: true, runnable: false },
+    { name: 'handlers', nested: false, synced: true, runnable: true },
+  ],
+  // The files/dirs `init` scaffolds offline, written from the CLI's bundled
+  // templates (src/templates/). Online, the server descriptor's `scaffold` +
+  // `templates` (keyed by path) take over.
+  scaffold: [
+    'schema.js',
+    'lib/',
+    'handlers/',
+    'handlers/message.js',
+    // Project docs aimed at AI coding assistants: an orientation file at the root
+    // and the SDK reference under docs/. init doesn't track .md in init_templates,
+    // so they scaffold but never deploy.
+    'AGENTS.md',
+    'docs/',
+    'docs/tgcloud-sdk.md',
+  ],
+};
+
+// Root file *names* stay baseline-driven (schema.js is fixed); the server may
+// override their *content* via `templates` (keyed by path), but not the names.
+export const ROOT_FILE = BASELINE.rootFiles[0].name;
+export const ROOT_FILES = BASELINE.rootFiles.map((f) => f.name);
+
+// Sanitization is the security boundary: the descriptor drives which directories
+// the CLI scans and which files it writes, so names/paths are strictly checked.
+const SAFE_SEGMENT = /^[a-z0-9_-]+$/i;
+const SAFE_FILE = /^[a-z0-9_-]+(\.[a-z0-9]+)+$/i;
+const FORBIDDEN = new Set(['.tgcloud', '.git', 'node_modules', '.', '..']);
+
+const MAX_TEMPLATES = 100;
+const MAX_TEMPLATE_BYTES = 64 * 1024;
+const MAX_SCAFFOLD = 200;
+const MAX_PATH_SEGMENTS = 8;
+
+/**
+ * Validate a relative path from the descriptor (a scaffold entry or a templates
+ * key). Returns the normalized path or null if unsafe. This is where the CLI
+ * decides what files a server may create on the user's machine, so it is
+ * deliberately strict: every segment is checked, and anything absolute, escaping
+ * (`..`), hidden (`.x`), backslash-bearing, over-deep, or naming a reserved dir
+ * is rejected.
+ *
+ *   opts.dir === true → also accept a trailing-slash directory entry ("lib/").
+ */
+export function sanitizeRelPath(p, opts = {}) {
+  if (typeof p !== 'string' || !p) return null;
+  if (p.includes('\\')) return null;   // no Windows separators / escapes
+  if (p.startsWith('/')) return null;  // no absolute paths
+  const isDir = p.endsWith('/');
+  if (isDir && !opts.dir) return null; // templates keys must be files, not dirs
+  const body = isDir ? p.slice(0, -1) : p;
+  const segments = body.split('/');
+  if (!segments.length || segments.length > MAX_PATH_SEGMENTS) return null;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (!seg) return null;               // empty: "", "a//b", leading/trailing slash
+    if (/[\x00-\x1f\x7f]/.test(seg)) return null; // control chars incl. a trailing \n the `$` anchor would otherwise allow
+    if (FORBIDDEN.has(seg.toLowerCase())) return null;  // ".", "..", ".tgcloud", ".git", "node_modules" (case-folded: FS is often case-insensitive)
+    const isFilePart = !isDir && i === segments.length - 1;
+    if (isFilePart) {
+      if (!SAFE_FILE.test(seg)) return null;   // final file part: name(.ext)+
+    } else if (!SAFE_SEGMENT.test(seg)) {
+      return null;                             // directory segment
+    }
+  }
+  return isDir ? `${body}/` : body;
+}
+
+function sanitizeDirectory(d) {
+  if (!d || typeof d.name !== 'string') return null;
+  if (!SAFE_SEGMENT.test(d.name) || FORBIDDEN.has(d.name.toLowerCase())) return null;
+  // Only known flags are honored; unknown flags are ignored (forward-compat).
+  const dir = {
+    name: d.name,
+    nested: d.nested === true,
+    synced: d.synced !== false, // default true
+    runnable: d.runnable === true,
+  };
+  // Optional closed vocabulary of module names allowed in this directory (e.g.
+  // handlers/ = Bot API update types). Absent → any safe name is allowed.
+  if (Array.isArray(d.allowed_names)) {
+    const names = d.allowed_names.filter((n) => typeof n === 'string' && SAFE_SEGMENT.test(n));
+    if (names.length) dir.allowedNames = names;
+  }
+  return dir;
+}
+
+function sanitizeRootFile(f) {
+  if (!f || typeof f.name !== 'string') return null;
+  if (!SAFE_FILE.test(f.name) || FORBIDDEN.has(f.name.toLowerCase())) return null;
+  return { name: f.name, singleton: f.singleton === true };
+}
+
+// A scaffold entry is a directory ("lib/") or a file — possibly nested
+// ("docs/guide.md", "handlers/message.js").
+function sanitizeScaffoldEntry(e) {
+  return sanitizeRelPath(e, { dir: true });
+}
+
+// `templates` is a map { key: content }. A key is either a file path (an `init`
+// starter, e.g. "handlers/message.js") or a directory ("handlers/") — the
+// per-directory starter used by `tgcloud add`. Content must be a string within
+// the size cap; the whole map is capped.
+function sanitizeTemplates(raw) {
+  if (!raw || typeof raw !== 'object') return {};
+  const out = {};
+  let count = 0;
+  for (const [key, content] of Object.entries(raw)) {
+    if (count >= MAX_TEMPLATES) break;
+    const path = sanitizeRelPath(key, { dir: true });
+    if (!path) continue;
+    if (typeof content !== 'string') continue;
+    if (Buffer.byteLength(content, 'utf-8') > MAX_TEMPLATE_BYTES) continue;
+    out[path] = content;
+    count++;
+  }
+  return out;
+}
+
+/**
+ * Validate + sanitize a raw descriptor (from the server or read from cache).
+ * Returns a normalized descriptor, or null if it can't be trusted at all — in
+ * which case callers fall back to BASELINE.
+ *
+ * `directories` is the core: a descriptor with no usable directories is rejected
+ * wholesale. The optional `root_files`/`templates`/`scaffold` fields are
+ * sanitized independently; if any is malformed it is simply dropped and the
+ * baseline fills in for that aspect (see effective()). Forward-compatible: a
+ * higher project_schema_version still validates.
+ */
+export function validateDescriptor(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  if (typeof raw.project_schema_version !== 'number') return null;
+
+  const directories = Array.isArray(raw.directories)
+    ? raw.directories.map(sanitizeDirectory).filter(Boolean)
+    : [];
+  if (!directories.length) return null;
+
+  const rootFiles = Array.isArray(raw.root_files)
+    ? raw.root_files.map(sanitizeRootFile).filter(Boolean)
+    : [];
+
+  const scaffold = Array.isArray(raw.scaffold)
+    ? raw.scaffold.slice(0, MAX_SCAFFOLD).map(sanitizeScaffoldEntry).filter(Boolean)
+    : [];
+
+  return {
+    project_schema_version: raw.project_schema_version,
+    directories,
+    rootFiles,
+    scaffold,
+    templates: sanitizeTemplates(raw.templates),
+  };
+}
+
+// What `init` should create when a valid descriptor carries no scaffold list:
+// each root file, then each directory as "name/". (Minimal — the baseline's
+// richer scaffold, with docs/starters, only applies offline.)
+function synthesizeScaffold(rootFiles, directories) {
+  return [
+    ...rootFiles.map((f) => f.name),
+    ...directories.map((d) => `${d.name}/`),
+  ];
+}
+
+// Memoized effective layout for this process. core/capabilities.js calls
+// resetLayout() after writing a fresh descriptor so later reads pick it up.
+let _effective;
+
+function effective() {
+  if (!_effective) {
+    const valid = validateDescriptor(loadCachedCapabilities());
+    const directories = valid ? valid.directories : BASELINE.directories;
+    const rootFiles = valid && valid.rootFiles.length ? valid.rootFiles : BASELINE.rootFiles;
+    const templates = valid ? valid.templates : {};
+    // Online: use the server's scaffold, or a minimal synthesized one if it
+    // omitted scaffold. Offline: the baseline's full scaffold (incl. docs/starters).
+    const scaffold = valid
+      ? (valid.scaffold.length ? valid.scaffold : synthesizeScaffold(rootFiles, directories))
+      : BASELINE.scaffold;
+    _effective = { directories, rootFiles, templates, scaffold };
+  }
+  return _effective;
+}
+
+export function resetLayout() {
+  _effective = undefined;
+}
+
+/** All module directory names, in declaration order. */
+export function moduleDirs() {
+  return effective().directories.map((d) => d.name);
+}
+
+/** Directories whose modules belong to the deployed space (the deploy manifest). */
+export function syncedDirs() {
+  return effective().directories.filter((d) => d.synced).map((d) => d.name);
+}
+
+/** Directories that may contain subdirectories (nested module names). */
+export function nestableDirs() {
+  return new Set(
+    effective().directories.filter((d) => d.nested).map((d) => d.name)
+  );
+}
+
+/** Directories whose modules can be invoked via `tgcloud run`. */
+export function runnableDirs() {
+  return effective().directories.filter((d) => d.runnable).map((d) => d.name);
+}
+
+/** Root-file entries ({ name, singleton }). */
+export function rootFileEntries() {
+  return effective().rootFiles;
+}
+
+/** The effective directory descriptor by name (with flags/allowedNames/template), or null. */
+export function directoryByName(name) {
+  return effective().directories.find((d) => d.name === name) || null;
+}
+
+/** Map { relativePath: content } of server-provided template contents (may be empty). */
+export function templates() {
+  return effective().templates;
+}
+
+/** Ordered list of files/dirs `init` should scaffold (dirs end with "/"). */
+export function scaffoldEntries() {
+  return effective().scaffold;
+}
+
+/**
+ * Given working-dir file paths, return modules that sit in a directory which
+ * declares `allowed_names` but whose name isn't in that list. Lets the CLI
+ * reject e.g. handlers/start.js locally (with the valid list) instead of only
+ * at the deploy round-trip. No-op until the server advertises allowed_names.
+ */
+export function findDisallowedModules(files) {
+  const byDir = new Map(
+    effective().directories.filter((d) => d.allowedNames).map((d) => [d.name, d.allowedNames])
+  );
+  if (!byDir.size) return [];
+  const out = [];
+  for (const f of files) {
+    const parts = f.split(/[\\/]/);
+    if (parts.length < 2) continue; // root files have no directory
+    const allowed = byDir.get(parts[0]);
+    if (!allowed) continue;
+    const name = parts[parts.length - 1].replace(/\.js$/, '');
+    if (!allowed.includes(name)) out.push({ file: f, dir: parts[0], name, allowed });
+  }
+  return out;
+}

package/src/core/project-root.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+
+const TGCLOUD_DIR = '.tgcloud';
+
+function isProjectDir(dir) {
+  try {
+    return fs.statSync(path.join(dir, TGCLOUD_DIR)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate the tgcloud project root: the nearest ancestor of `start` (inclusive)
+ * that contains a `.tgcloud/` directory — the same way git finds a repo by
+ * `.git/`. Returns the absolute directory path, or null if none is found up to
+ * the filesystem root.
+ *
+ * This is what lets a tgcloud project live in a dedicated folder (its own repo,
+ * or a subfolder of a larger repo) and be driven from any subdirectory.
+ */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (isProjectDir(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root
+    dir = parent;
+  }
+}
+
+/**
+ * Change into the project root so all CWD-relative file access (state, snapshot,
+ * scanner, working-dir reads/writes) resolves against the project — the single
+ * mechanism that makes running from a subdirectory work, without threading a
+ * root prefix through every fs call.
+ *
+ * No-op when no project is found: a not-yet-initialized directory keeps today's
+ * CWD-relative behavior, so `init` and the first `fetch`/`deploy` create
+ * `.tgcloud/` in the current directory. Returns the root, or null.
+ */
+export function enterProjectRoot() {
+  const root = findProjectRoot();
+  if (root && root !== process.cwd()) process.chdir(root);
+  return root;
+}