@sakupa/mcp 0.7.32 → 0.7.33

package/dist/index.js

@@ -124,7 +124,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.32";
+var SAKUPA_MCP_VERSION = "0.7.33";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -1217,7 +1217,7 @@ function normalizeOutputDir(outputDir) {
   return normalized === "" ? "." : normalized;
 }
 async function analyzeProject(projectDir, opts = {}) {
-  const root = resolve(projectDir);
+  const root = await fs.realpath(resolve(projectDir));
   const pkg = await readPackageJson(root);
   const detection = await detectFramework(root, pkg);
   const ssrRisks = [...detection?.ssrRisks ?? []];
@@ -1233,6 +1233,16 @@ async function analyzeProject(projectDir, opts = {}) {
       outputDirExists = false;
     } else {
       outputDirExists = await isDirectory(abs) || outputDirRel === "." && await isDirectory(root);
+      if (outputDirExists) {
+        try {
+          const physical = await fs.realpath(abs);
+          if (physical !== root && !physical.startsWith(root + sep)) {
+            outputDirExists = false;
+          }
+        } catch {
+          outputDirExists = false;
+        }
+      }
     }
   } else if (detection) {
     for (const candidate of detection.outputCandidates) {
@@ -1356,9 +1366,258 @@ async function analyzeProject(projectDir, opts = {}) {
 
 // src/tools/context.ts
 import { z as z2 } from "zod";
-import { statSync } from "node:fs";
+
+// src/project-root.ts
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync as chmodSync2,
+  existsSync as existsSync2,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, parse, resolve as resolve2 } from "node:path";
+import { dirname as dirname2, isAbsolute, join as join3, parse, relative, resolve as resolve2, sep as sep2 } from "node:path";
+var SAKUPA_DIR = ".sakupa";
+var PROJECT_FILE = "project.json";
+var SITE_FILE2 = "site.json";
+var RECOVERY_FILE2 = "recovery.json";
+var PROJECT_SCHEMA_VERSION = 1;
+var ProjectRootError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ProjectRootError";
+    this.code = code;
+  }
+};
+function projectMarkerPath(projectDir) {
+  return join3(projectDir, SAKUPA_DIR, PROJECT_FILE);
+}
+function loadProjectMarker(projectDir) {
+  const path = projectMarkerPath(projectDir);
+  if (!existsSync2(path)) return { kind: "absent" };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } catch (error) {
+    return {
+      kind: "corrupted",
+      problem: `the file cannot be read as JSON (${error instanceof Error ? error.message : String(error)})`
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { kind: "corrupted", problem: "the file does not contain a JSON object" };
+  }
+  const record = parsed;
+  if (record.schemaVersion !== PROJECT_SCHEMA_VERSION) {
+    return {
+      kind: "corrupted",
+      problem: `unsupported schemaVersion ${String(record.schemaVersion)}`
+    };
+  }
+  if (typeof record.projectId !== "string" || !isUuid(record.projectId)) {
+    return { kind: "corrupted", problem: "projectId is missing or is not a UUID" };
+  }
+  if (typeof record.createdAt !== "string" || !Number.isFinite(Date.parse(record.createdAt))) {
+    return { kind: "corrupted", problem: "createdAt is missing or invalid" };
+  }
+  if (record.outputDir !== void 0 && (typeof record.outputDir !== "string" || !isSafeRelativeOutput(record.outputDir))) {
+    return { kind: "corrupted", problem: "outputDir is not a safe project-relative path" };
+  }
+  return {
+    kind: "ok",
+    marker: {
+      schemaVersion: PROJECT_SCHEMA_VERSION,
+      projectId: record.projectId,
+      createdAt: record.createdAt,
+      ...record.outputDir !== void 0 ? { outputDir: normalizeRelative(record.outputDir) } : {}
+    }
+  };
+}
+function initializeProject(projectDir) {
+  const canonical = canonicalProjectDirectory(projectDir);
+  assertSafeProjectRoot(canonical);
+  const current = loadProjectMarker(canonical);
+  if (current.kind === "corrupted") {
+    throw new ProjectRootError(
+      "corrupted_marker",
+      `Refusing to overwrite damaged Sakupa project marker ${projectMarkerPath(canonical)}: ${current.problem}.`
+    );
+  }
+  if (current.kind === "ok") {
+    return {
+      projectDir: canonical,
+      requestedPath: canonical,
+      markerKind: "project",
+      marker: current.marker
+    };
+  }
+  const marker = {
+    schemaVersion: PROJECT_SCHEMA_VERSION,
+    projectId: randomUUID(),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeMarkerAtomically(canonical, marker);
+  return {
+    projectDir: canonical,
+    requestedPath: canonical,
+    markerKind: "project",
+    marker
+  };
+}
+function resolveProjectRoot(requestedPath) {
+  if (!isAbsolute(requestedPath)) {
+    throw new ProjectRootError(
+      "invalid_path",
+      `Project path must be absolute (got "${requestedPath}").`
+    );
+  }
+  const canonicalRequested = canonicalExistingPath(requestedPath);
+  const requestedStat = statSync(canonicalRequested);
+  let cursor = requestedStat.isDirectory() ? canonicalRequested : dirname2(canonicalRequested);
+  const startDevice = statSync(cursor).dev;
+  const candidates = [];
+  while (true) {
+    if (statSync(cursor).dev !== startDevice) break;
+    const markerState = loadProjectMarker(cursor);
+    const hasSite = existsSync2(join3(cursor, SAKUPA_DIR, SITE_FILE2));
+    const hasRecovery = existsSync2(join3(cursor, SAKUPA_DIR, RECOVERY_FILE2));
+    if (markerState.kind !== "absent" || hasSite || hasRecovery) {
+      candidates.push({ dir: cursor, markerState, hasSite, hasRecovery });
+    }
+    const parent = dirname2(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  if (candidates.length === 0) {
+    throw new ProjectRootError(
+      "not_initialized",
+      `No Sakupa project marker was found at or above ${canonicalRequested}. Run \`npx -y @sakupa/mcp@latest init\` once from the intended project root; no site was changed.`
+    );
+  }
+  const nearest = candidates[0];
+  if (nearest.markerState.kind === "corrupted") {
+    throw new ProjectRootError(
+      "corrupted_marker",
+      `Sakupa project marker ${projectMarkerPath(nearest.dir)} is damaged: ${nearest.markerState.problem}.`
+    );
+  }
+  if (nearest.markerState.kind === "absent") {
+    const explicitAncestor = candidates.find((candidate) => candidate.markerState.kind === "ok");
+    if (explicitAncestor) {
+      throw new ProjectRootError(
+        "ambiguous_binding",
+        `A legacy .sakupa binding exists at ${nearest.dir}, below the initialized Sakupa project ${explicitAncestor.dir}. Start the operation from ${explicitAncestor.dir}; deploy can then validate and relocate the same credential without creating a site.`
+      );
+    }
+  }
+  assertSafeProjectRoot(nearest.dir);
+  if (nearest.markerState.kind === "ok") {
+    return {
+      projectDir: nearest.dir,
+      requestedPath: canonicalRequested,
+      markerKind: "project",
+      marker: nearest.markerState.marker
+    };
+  }
+  return {
+    projectDir: nearest.dir,
+    requestedPath: canonicalRequested,
+    markerKind: nearest.hasSite ? "legacy_site" : "legacy_recovery"
+  };
+}
+function updateProjectOutputDir(projectDir, outputDir) {
+  const canonical = canonicalProjectDirectory(projectDir);
+  const state = loadProjectMarker(canonical);
+  if (state.kind !== "ok") {
+    throw new ProjectRootError(
+      state.kind === "corrupted" ? "corrupted_marker" : "not_initialized",
+      state.kind === "corrupted" ? `Cannot update damaged Sakupa project marker: ${state.problem}.` : `No Sakupa project marker exists in ${canonical}.`
+    );
+  }
+  if (!isSafeRelativeOutput(outputDir)) {
+    throw new ProjectRootError(
+      "unsafe_path",
+      `Output directory "${outputDir}" must stay inside the initialized Sakupa project.`
+    );
+  }
+  const marker = {
+    ...state.marker,
+    outputDir: normalizeRelative(outputDir)
+  };
+  writeMarkerAtomically(canonical, marker);
+  return marker;
+}
+function canonicalProjectDirectory(path) {
+  const canonical = canonicalExistingPath(resolve2(path));
+  if (!statSync(canonical).isDirectory()) {
+    throw new ProjectRootError("invalid_path", `Project path ${canonical} is not a directory.`);
+  }
+  return canonical;
+}
+function canonicalExistingPath(path) {
+  try {
+    const stat2 = lstatSync(path, { throwIfNoEntry: false });
+    if (!stat2) {
+      throw new ProjectRootError("invalid_path", `Project path ${path} does not exist.`);
+    }
+    return realpathSync(path);
+  } catch (error) {
+    if (error instanceof ProjectRootError) throw error;
+    throw new ProjectRootError(
+      "invalid_path",
+      `Project path ${path} cannot be resolved (${error instanceof Error ? error.message : String(error)}).`
+    );
+  }
+}
+function assertSafeProjectRoot(projectDir) {
+  if (parse(projectDir).root === projectDir || projectDir === realpathSync(homedir())) {
+    throw new ProjectRootError(
+      "unsafe_path",
+      `Refusing to use ${projectDir} as a Sakupa project root; choose a specific project directory.`
+    );
+  }
+}
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function normalizeRelative(path) {
+  const normalized = path.split(sep2).join("/").replace(/^\.\//, "").replace(/\/$/, "");
+  return normalized.length === 0 ? "." : normalized;
+}
+function isSafeRelativeOutput(path) {
+  if (path.length === 0 || isAbsolute(path)) return false;
+  const normalized = normalizeRelative(path);
+  if (normalized === ".") return true;
+  const rel = relative("/sakupa-root", resolve2("/sakupa-root", normalized));
+  return rel !== ".." && !rel.startsWith(`..${sep2}`) && !isAbsolute(rel);
+}
+function writeMarkerAtomically(projectDir, marker) {
+  const dir = join3(projectDir, SAKUPA_DIR);
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  const path = projectMarkerPath(projectDir);
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync2(temporary, `${JSON.stringify(marker, null, 2)}
+`, {
+      encoding: "utf8",
+      mode: 384
+    });
+    renameSync(temporary, path);
+    try {
+      chmodSync2(path, 384);
+    } catch {
+    }
+  } finally {
+    if (existsSync2(temporary)) unlinkSync(temporary);
+  }
+}
 
 // src/tools/result.ts
 import { z } from "zod";
@@ -1408,36 +1667,33 @@ var LocalGuidanceError = class extends SakupaError {
   }
 };
 var projectDirInput = z2.string().describe(
-  "REQUIRED on every call: absolute path of the user's PROJECT ROOT \u2014 the folder the user opened/works in (for framework projects: where package.json lives, NEVER the build-output subfolder like dist/out; the analyzer locates the output automatically). .sakupa/site.json lives here, so PASS THE SAME DIRECTORY EVERY TIME for the same project. Only YOU know which directory the user is in \u2014 the server never guesses and refuses calls without it."
+  "REQUIRED: an absolute existing path anywhere inside the user's initialized Sakupa project (the root itself or a child such as dist/html/src). Sakupa resolves upward to its own .sakupa marker and never trusts this argument as the root. If no marker exists, run `npx -y @sakupa/mcp@latest init` once from the intended project root."
 );
 function withProjectDir(ctx, projectDirArg) {
   if (projectDirArg === void 0) {
     throw new LocalGuidanceError(
       "invalid_request",
-      "projectDir is REQUIRED on every call: pass the absolute path of the directory the user is CURRENTLY working in. The server never guesses a directory \u2014 a wrong guess once published one project's files over a different project's PAID site."
-    );
-  }
-  if (!isAbsolute(projectDirArg)) {
-    throw new LocalGuidanceError(
-      "invalid_request",
-      `projectDir must be an ABSOLUTE path (got "${projectDirArg}"). Pass the full path of the directory the user is currently working in.`
-    );
-  }
-  const dir = resolve2(projectDirArg);
-  if (parse(dir).root === dir || dir === homedir()) {
-    throw new LocalGuidanceError(
-      "invalid_request",
-      `projectDir "${dir}" is a filesystem root or the home directory. Pass the specific project folder that holds the site's files, not a top-level directory.`
+      "projectDir is REQUIRED as a path locator: pass an absolute existing path anywhere inside the current Sakupa project. The server resolves its own .sakupa marker and never treats the supplied path as an authoritative root."
     );
   }
-  const stat2 = statSync(dir, { throwIfNoEntry: false });
-  if (!stat2?.isDirectory()) {
-    throw new LocalGuidanceError(
-      "invalid_request",
-      `projectDir "${dir}" does not exist or is not a directory. Pass the absolute path of the directory the user is currently working in.`
-    );
+  try {
+    const resolved = resolveProjectRoot(projectDirArg);
+    return {
+      ...ctx,
+      projectDir: resolved.projectDir,
+      requestedPath: resolved.requestedPath,
+      markerKind: resolved.markerKind,
+      ...resolved.marker !== void 0 ? { projectMarker: resolved.marker } : {}
+    };
+  } catch (error) {
+    if (error instanceof ProjectRootError) {
+      throw new LocalGuidanceError(
+        error.code === "not_initialized" ? "not_found" : "invalid_request",
+        error.message
+      );
+    }
+    throw error;
   }
-  return { ...ctx, projectDir: dir };
 }
 function requireSiteFile(ctx) {
   const state = loadSiteFile(ctx.projectDir);
@@ -1494,14 +1750,15 @@ function toolError(e) {
 }
 
 // src/tools/definitions.ts
-import { randomUUID } from "node:crypto";
-import { existsSync as existsSync3, promises as fs2 } from "node:fs";
-import { join as join5, relative as relative2, resolve as resolve4, sep as sep3 } from "node:path";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { promises as fs2 } from "node:fs";
+import { join as join6, resolve as resolve4 } from "node:path";
 import { z as z3 } from "zod";
 
 // src/recovery-archive.ts
+import { existsSync as existsSync3, realpathSync as realpathSync2 } from "node:fs";
 import { mkdtemp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve3, sep as sep2 } from "node:path";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join4, relative as relative2, resolve as resolve3, sep as sep3 } from "node:path";
 
 // ../../node_modules/fflate/esm/index.mjs
 import { createRequire } from "module";
@@ -1991,15 +2248,30 @@ function safeOutputPath(projectDir, outputDir) {
   if (outputDir.length === 0 || isAbsolute2(outputDir)) {
     throw new SakupaError("invalid_request", "Recovery outputDir must be a relative directory");
   }
-  const root = resolve3(projectDir);
+  const root = realpathSync2(resolve3(projectDir));
   const target = resolve3(root, outputDir);
-  const rel = relative(root, target);
-  if (rel === "" || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute2(rel)) {
+  const rel = relative2(root, target);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep3}`) || isAbsolute2(rel)) {
     throw new SakupaError("invalid_request", "Recovery outputDir must stay inside projectDir");
   }
-  if (rel === ".sakupa" || rel.startsWith(`.sakupa${sep2}`)) {
+  if (rel === ".sakupa" || rel.startsWith(`.sakupa${sep3}`)) {
     throw new SakupaError("invalid_request", "Recovery content cannot be written inside .sakupa");
   }
+  let existingAncestor = target;
+  while (!existsSync3(existingAncestor)) {
+    const parent = dirname3(existingAncestor);
+    if (parent === existingAncestor) break;
+    existingAncestor = parent;
+  }
+  const physicalAncestor = realpathSync2(existingAncestor);
+  const physicalTarget = resolve3(physicalAncestor, relative2(existingAncestor, target));
+  const physicalRel = relative2(root, physicalTarget);
+  if (physicalRel === ".." || physicalRel.startsWith(`..${sep3}`) || isAbsolute2(physicalRel)) {
+    throw new SakupaError(
+      "invalid_request",
+      "Recovery outputDir resolves through a symlink outside projectDir"
+    );
+  }
   return target;
 }
 function safeEntryName(name) {
@@ -2028,9 +2300,9 @@ async function listExistingFiles(root, current = root) {
     if (entry.isSymbolicLink()) {
       throw new SakupaError("state_conflict", `Recovery output contains a symlink: ${entry.name}`);
     }
-    const absolute = join3(current, entry.name);
+    const absolute = join4(current, entry.name);
     if (entry.isDirectory()) files.push(...await listExistingFiles(root, absolute));
-    else if (entry.isFile()) files.push(relative(root, absolute).split(sep2).join("/"));
+    else if (entry.isFile()) files.push(relative2(root, absolute).split(sep3).join("/"));
     else
       throw new SakupaError(
         "state_conflict",
@@ -2046,7 +2318,7 @@ async function existingOutputMatches(outputDir, files) {
     return false;
   }
   for (const name of expected) {
-    const actual = await readFile(join3(outputDir, ...name.split("/")));
+    const actual = await readFile(join4(outputDir, ...name.split("/")));
     const wanted = files[name];
     if (!wanted || actual.byteLength !== wanted.byteLength || !actual.equals(wanted)) return false;
   }
@@ -2056,7 +2328,7 @@ async function extractRecoveryArchive(input) {
   if (!Number.isSafeInteger(input.expectedBytes) || input.expectedBytes < 0 || input.expectedBytes > PAID_SITE_MAX_TOTAL_BYTES || !Number.isSafeInteger(input.expectedFiles) || input.expectedFiles < 0 || input.expectedFiles > MAX_FILE_COUNT) {
     throw new SakupaError("validation_failed", "Recovery archive metadata exceeds product limits");
   }
-  const outputDir = safeOutputPath(input.projectDir, input.outputDir ?? "html");
+  const outputDir = safeOutputPath(input.projectDir, input.outputDir);
   const maxArchiveBytes = input.expectedBytes + input.expectedFiles * 4096 + 65536;
   if (input.archive.byteLength > maxArchiveBytes) {
     throw new SakupaError("validation_failed", "Recovery archive is larger than its site metadata");
@@ -2097,14 +2369,14 @@ async function extractRecoveryArchive(input) {
       `Recovery output already exists with different content: ${outputDir}. Move it aside or choose another outputDir.`
     );
   }
-  const tempDir = await mkdtemp(join3(resolve3(input.projectDir), ".sakupa-restore-"));
+  const tempDir = await mkdtemp(join4(resolve3(input.projectDir), ".sakupa-restore-"));
   try {
     let writtenBytes = 0;
     const entries = Object.entries(files).sort(([a], [b]) => a.localeCompare(b));
     for (const [rawName, data] of entries) {
       const name = safeEntryName(rawName);
-      const destination = join3(tempDir, ...name.split("/"));
-      await mkdir(dirname2(destination), { recursive: true });
+      const destination = join4(tempDir, ...name.split("/"));
+      await mkdir(dirname3(destination), { recursive: true });
       await writeFile(destination, data, { flag: "wx" });
       writtenBytes += data.byteLength;
     }
@@ -2114,7 +2386,7 @@ async function extractRecoveryArchive(input) {
         "Extracted recovery data does not match site metadata"
       );
     }
-    await mkdir(dirname2(outputDir), { recursive: true });
+    await mkdir(dirname3(outputDir), { recursive: true });
     await rename(tempDir, outputDir);
     return {
       outputDir,
@@ -2129,19 +2401,19 @@ async function extractRecoveryArchive(input) {
 }
 
 // src/creation-registry.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname3, join as join4 } from "node:path";
+import { dirname as dirname4, join as join5 } from "node:path";
 var RECENT_WINDOW_MS = FREE_SITE_TTL_HOURS * 60 * 60 * 1e3;
 function creationRegistryPath() {
   const base = process.env["SAKUPA_STATE_DIR"] ?? homedir2();
-  return join4(base, ".sakupa", "created-sites.json");
+  return join5(base, ".sakupa", "created-sites.json");
 }
 function readAll() {
   const path = creationRegistryPath();
-  if (!existsSync2(path)) return [];
+  if (!existsSync4(path)) return [];
   try {
-    const parsed = JSON.parse(readFileSync2(path, "utf-8"));
+    const parsed = JSON.parse(readFileSync3(path, "utf-8"));
     if (!Array.isArray(parsed)) return [];
     return parsed.filter(
       (e) => typeof e === "object" && e !== null && typeof e.siteId === "string" && typeof e.createdAt === "string"
@@ -2152,8 +2424,8 @@ function readAll() {
 }
 function writeAll(records) {
   const path = creationRegistryPath();
-  mkdirSync2(dirname3(path), { recursive: true });
-  writeFileSync2(path, `${JSON.stringify(records, null, 2)}
+  mkdirSync3(dirname4(path), { recursive: true });
+  writeFileSync3(path, `${JSON.stringify(records, null, 2)}
 `, "utf-8");
 }
 function listRecentCreations(nowMs, apiBaseUrl) {
@@ -2381,7 +2653,7 @@ function ensureUploadSizeWithinLimits(manifest, isFirstFreeDeploy) {
 async function buildHashedManifest(files, outputAbs) {
   const manifest = [];
   for (const file of files) {
-    const bytes = new Uint8Array(await fs2.readFile(join5(outputAbs, file.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join6(outputAbs, file.path)));
     manifest.push({ path: file.path, size: file.size, contentHash: await sha256Hex(bytes) });
   }
   return manifest;
@@ -2400,7 +2672,7 @@ async function uploadAll(ctx, targets, files, outputAbs) {
         `No local file matches upload target "${target.path}"; aborting upload.`
       );
     }
-    const bytes = new Uint8Array(await fs2.readFile(join5(outputAbs, match.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join6(outputAbs, match.path)));
     if (bytes.byteLength !== match.size) {
       throw new SakupaError(
         "validation_failed",
@@ -2443,21 +2715,6 @@ ${block}`, checklist: toDnsChecklist(diag.checks) };
     };
   }
 }
-function projectRootAbove(projectDir) {
-  if (existsSync3(join5(projectDir, "package.json"))) return null;
-  const packageRoot = findAncestor(projectDir, (dir) => existsSync3(join5(dir, "package.json")), 4);
-  if (packageRoot) {
-    return {
-      projectRoot: packageRoot,
-      outputDir: relative2(packageRoot, projectDir).split(sep3).join("/")
-    };
-  }
-  return null;
-}
-function findNeighborBinding(projectDir) {
-  const bound = (dir) => loadSiteFile(dir).kind !== "absent";
-  return findAncestor(projectDir, bound, 3);
-}
 function freeSiteCreationBarrier(apiBaseUrl) {
   const recent = listRecentCreations(Date.now(), apiBaseUrl);
   if (recent.length < FREE_ACTIVE_SITES_PER_IP) return null;
@@ -2508,13 +2765,16 @@ Next action: ${analysis.suggestedNextAction}`,
   server.registerTool(
     "deploy",
     {
-      description: `Deploy the local static output to Sakupa. First deploy creates a free temporary site (valid ${FREE_SITE_TTL_HOURS}h, public URL like https://${previewHostPattern}) and stores the management credential in .sakupa/site.json. Later runs update the existing site (free sites also refresh their validity; subscribed sites are permanent). Runs analyze first and refuses to upload source projects, secrets, .env files, archives, media or server code. projectDir is ALWAYS the project root where .sakupa belongs; outputDir is a separate REQUIRED relative path supplied from the current project inspection ("." when the root itself is published). NEVER pass the build/output folder as projectDir. Never uploads anything when analysis says the project is not deployable.`,
+      description: `Deploy the local static output to Sakupa. First deploy creates a free temporary site (valid ${FREE_SITE_TTL_HOURS}h, public URL like https://${previewHostPattern}) and stores the management credential in .sakupa/site.json. Later runs update the existing site (free sites also refresh their validity; subscribed sites are permanent). Runs analyze first and refuses to upload source projects, secrets, .env files, archives, media or server code. projectDir may point anywhere inside a project already initialized with \`npx -y @sakupa/mcp@latest init\`; Sakupa resolves its own marker upward and stores credentials only at that root. outputDir is a separate REQUIRED relative path supplied from the current project inspection. Never uploads anything when analysis says the project is not deployable.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
         projectDir: projectDirInput,
         outputDir: z3.string().min(1).describe(
-          'REQUIRED: exact publish directory relative to projectDir, supplied by the AI after inspecting this project (for example ".", "dist", "html", or any custom build directory). NEVER put this path in projectDir; .sakupa belongs at projectDir.'
+          'REQUIRED: exact publish directory relative to the initialized project root, supplied by the AI after inspecting this project (for example ".", "dist", "html", or any custom build directory). Sakupa resolves projectDir upward before applying this path.'
+        ),
+        outputDirChangeConfirmed: z3.boolean().optional().describe(
+          "Required only when changing the previously successful publish directory. Confirm only after showing the old and new directories to the user."
         ),
         spaFallback: z3.boolean().optional().describe(
           "Override automatic SPA-fallback detection (single index.html + JS auto-enables rewriting unknown paths to index.html; multiple HTML pages auto-disable it). Pass only to force the behavior against the detected structure."
@@ -2523,7 +2783,7 @@ Next action: ${analysis.suggestedNextAction}`,
           "Required only for the first deployment: user explicitly confirmed creation of a public 24-hour URL."
         ),
         subprojectConfirmed: z3.boolean().optional().describe(
-          "Only when creating a NEW site in a subfolder of a package.json project: the user explicitly confirmed this subfolder is an INDEPENDENT site, not the project's build output."
+          "Deprecated compatibility field. Project independence is established only by `sakupa-mcp init`, never inferred from package.json or folder names."
         ),
         lang: z3.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
       }
@@ -2535,8 +2795,25 @@ Next action: ${analysis.suggestedNextAction}`,
         if (!analysis.deployable || !analysis.files) {
           return notDeployableResult(analysis);
         }
+        const effectiveOutputDir = analysis.recommendedOutputDir ?? ".";
+        const recordedOutputDir = ctx.projectMarker?.outputDir;
+        if (recordedOutputDir !== void 0 && resolve4(ctx.projectDir, recordedOutputDir) !== resolve4(ctx.projectDir, effectiveOutputDir) && args.outputDirChangeConfirmed !== true) {
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "waiting_user",
+            resultCode: "publish_directory_change_confirmation_required",
+            summary: `This initialized project last published from "${recordedOutputDir}", but this request selected "${effectiveOutputDir}". Nothing was uploaded and the site was not changed. Show both paths to the user; only after explicit confirmation call deploy again with outputDirChangeConfirmed: true.`,
+            data: {
+              projectDir: ctx.projectDir,
+              previousOutputDir: recordedOutputDir,
+              requestedOutputDir: effectiveOutputDir,
+              confirmationField: "outputDirChangeConfirmed"
+            },
+            nextActions: [{ tool: "deploy", allowed: true, reasonCode: "explicit_confirmation" }]
+          });
+        }
         const files = analysis.files;
-        const outputAbs = resolve4(ctx.projectDir, analysis.recommendedOutputDir ?? ".");
+        const outputAbs = resolve4(ctx.projectDir, effectiveOutputDir);
         const manifest = await buildHashedManifest(files, outputAbs);
         const siteFileState = loadSiteFile(ctx.projectDir);
         if (siteFileState.kind === "corrupted") {
@@ -2551,7 +2828,16 @@ Next action: ${analysis.suggestedNextAction}`,
         }
         let existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         let credentialRelocatedFrom = null;
-        if (!existing && analysis.recommendedOutputDir !== ".") {
+        if (!existing && effectiveOutputDir !== ".") {
+          const outputProjectMarker = loadProjectMarker(outputAbs);
+          if (outputProjectMarker.kind !== "absent") {
+            return text(
+              "publish_directory_is_independent_project",
+              outputProjectMarker.kind === "corrupted" ? `The selected publish directory ${outputAbs} contains a damaged Sakupa project marker: ${outputProjectMarker.problem}. Nothing was deployed.` : `The selected publish directory ${outputAbs} is itself an explicitly initialized Sakupa project. Refusing to move or reuse its credential from ${ctx.projectDir}. Run deploy from that independent project instead, or choose a publish directory that is not another Sakupa project.`,
+              { projectRoot: ctx.projectDir, outputDir: effectiveOutputDir },
+              "blocked"
+            );
+          }
           const outputSiteState = loadSiteFile(outputAbs);
           if (outputSiteState.kind === "corrupted") {
             return text(
@@ -2562,35 +2848,11 @@ Next action: ${analysis.suggestedNextAction}`,
             );
           }
           if (outputSiteState.kind === "ok") {
-            writeSiteFile(ctx.projectDir, outputSiteState.file);
-            deleteSiteFile(outputAbs);
             existing = outputSiteState.file;
             credentialRelocatedFrom = outputAbs;
           }
         }
         if (!existing) {
-          const rootHint = args.subprojectConfirmed === true ? null : projectRootAbove(ctx.projectDir);
-          if (rootHint) {
-            return text(
-              "not_project_root",
-              `${ctx.projectDir} is a SUBFOLDER of a package.json project, and .sakupa must live at the project ROOT. Re-run deploy with projectDir: ${rootHint.projectRoot} and outputDir: ${rootHint.outputDir}. Only if the user explicitly says this subfolder is an INDEPENDENT site (e.g. a docs/ site inside a repo), re-run with subprojectConfirmed: true. Nothing was deployed and no site was created.`,
-              {
-                projectRoot: rootHint.projectRoot,
-                outputDir: rootHint.outputDir,
-                confirmationField: "subprojectConfirmed"
-              },
-              "blocked"
-            );
-          }
-          const neighbor = findNeighborBinding(ctx.projectDir);
-          if (neighbor) {
-            return text(
-              "neighbor_binding_found",
-              `No .sakupa binding in ${ctx.projectDir}, but one EXISTS at ${neighbor} \u2014 this looks like the same project addressed at a different directory level. To update that existing site, re-run deploy with projectDir: ${neighbor}. Only if the user explicitly wants a SEPARATE new site, move this deploy to a directory outside that project. Nothing was deployed and no site was created.`,
-              { neighborProjectDir: neighbor },
-              "blocked"
-            );
-          }
           const barrier = freeSiteCreationBarrier(ctx.apiBaseUrl);
           if (barrier) return barrier;
           if (args.publicConfirmed !== true) {
@@ -2624,6 +2886,7 @@ Next action: ${analysis.suggestedNextAction}`,
             createdAt,
             apiBaseUrl: ctx.apiBaseUrl
           });
+          updateProjectOutputDir(ctx.projectDir, effectiveOutputDir);
           recordCreation({
             siteId: created.siteId,
             projectDir: ctx.projectDir,
@@ -2698,6 +2961,9 @@ ${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
         }
         const { uploaded, finalized } = update;
         writeSiteFile(ctx.projectDir, { ...existing, url: finalized.url });
+        if (credentialRelocatedFrom !== null) deleteSiteFile(credentialRelocatedFrom);
+        if (ctx.projectMarker === void 0) initializeProject(ctx.projectDir);
+        updateProjectOutputDir(ctx.projectDir, effectiveOutputDir);
         noteSiteMode(existing.siteId, finalized.mode);
         return text(
           "site_updated",
@@ -2806,7 +3072,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID()
+            idempotencyKey: randomUUID2()
           },
           site.credential
         );
@@ -2996,14 +3262,14 @@ Full status:`, res);
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       inputSchema: {
-        projectDir: projectDirInput,
+        projectDir: projectDirInput.optional(),
         scope: z3.enum(["site", "public_recovery"])
       }
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx, args.projectDir);
         if (args.scope === "site") {
+          const ctx = withProjectDir(baseCtx, args.projectDir);
           const site = requireSiteFile(ctx);
           const res2 = await ctx.client.createBillingPortal(site.siteId, site.credential);
           return structuredToolResult({
@@ -3021,7 +3287,7 @@ Full status:`, res);
             nextActions: [{ tool: "billing", allowed: true }]
           });
         }
-        const res = await ctx.client.getPublicBillingPortal();
+        const res = await baseCtx.client.getPublicBillingPortal();
         return structuredToolResult({
           schemaVersion: 1,
           outcome: "waiting_user",
@@ -3049,7 +3315,7 @@ Full status:`, res);
   server.registerTool(
     "recover",
     {
-      description: "Recover management control of a subscribed site WITH A BOUND CUSTOM DOMAIN after losing the local project, by proving DNS control of the apex domain. Sites without a bound domain are identified solely by their local credential and cannot be recovered. By default, completing recovery REVOKES all previous local credentials. Recovery is resumable: start stores local pending state; complete installs and writes the new .sakupa/site.json credential BEFORE requesting content; download uses that credential to reissue an archive and safely extract it into html without repeating DNS.",
+      description: "Recover management control of a subscribed site WITH A BOUND CUSTOM DOMAIN after losing the local project, by proving DNS control of the apex domain. Sites without a bound domain are identified solely by their local credential and cannot be recovered. By default, completing recovery REVOKES all previous local credentials. Recovery is resumable: start stores local pending state; complete installs and writes the new .sakupa/site.json credential BEFORE requesting content; download uses that credential to reissue an archive and safely extract it into the explicitly selected outputDir without repeating DNS.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
@@ -3057,13 +3323,21 @@ Full status:`, res);
         action: z3.enum(["start", "status", "complete", "download"]),
         hostname: z3.string().optional().describe("Required for start."),
         verificationId: z3.string().optional().describe("For status or complete; inferred from local recovery state when omitted."),
-        outputDir: z3.string().optional().describe("Relative extraction directory for complete/download (default: html)."),
+        outputDir: z3.string().optional().describe(
+          "REQUIRED for complete/download: exact extraction directory relative to the initialized project root. Inspect the current project; Sakupa never guesses a name."
+        ),
         preserveExistingCredentials: z3.boolean().optional().describe("Explicitly keep old local credentials working (default: revoke them all).")
       }
     },
     async (args) => {
       try {
         const ctx = withProjectDir(baseCtx, args.projectDir);
+        if ((args.action === "complete" || args.action === "download") && args.outputDir === void 0) {
+          throw new LocalGuidanceError(
+            "invalid_request",
+            "recover requires outputDir for complete/download. Inspect the current project and pass the exact extraction directory relative to the initialized Sakupa root; the server never defaults to html, dist, build, or any other name."
+          );
+        }
         const localSite = loadSiteFile(ctx.projectDir);
         const localCredentialIsActive = async () => {
           if (localSite.kind !== "ok") return false;
@@ -3076,12 +3350,18 @@ Full status:`, res);
           }
         };
         const download = async () => {
+          if (args.outputDir === void 0) {
+            throw new LocalGuidanceError(
+              "invalid_request",
+              "recover download requires an explicit outputDir."
+            );
+          }
           const site = requireSiteFile(ctx);
           const archive = await ctx.client.getSiteArchive(site.siteId, site.credential);
           const bytes = await ctx.client.downloadArchive(archive.archiveUrl);
           const extracted = await extractRecoveryArchive({
             projectDir: ctx.projectDir,
-            ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {},
+            outputDir: args.outputDir,
             archive: bytes,
             expectedBytes: archive.totalBytes,
             expectedFiles: archive.fileCount
@@ -3126,7 +3406,7 @@ No DNS verification was started or repeated.`,
                   arguments: {
                     projectDir: ctx.projectDir,
                     action: "download",
-                    outputDir: args.outputDir ?? "html"
+                    ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
                   },
                   allowed: true
                 }
@@ -3226,7 +3506,7 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
                 arguments: {
                   projectDir: ctx.projectDir,
                   action: "download",
-                  outputDir: args.outputDir ?? "html"
+                  ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
                 },
                 allowed: true
               }
@@ -3262,7 +3542,7 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
                   projectDir: ctx.projectDir,
                   action: "complete",
                   verificationId,
-                  outputDir: args.outputDir ?? "html"
+                  ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
                 },
                 allowed: res2.readyToComplete,
                 ...res2.readyToComplete ? {} : { reasonCode: res2.status }
@@ -3338,7 +3618,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
                 arguments: {
                   projectDir: ctx.projectDir,
                   action: "download",
-                  outputDir: args.outputDir ?? "html"
+                  ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
                 },
                 allowed: true
               }
@@ -3458,7 +3738,7 @@ Summary: ${res.sanitizedSummary}`,
 }
 
 // src/tools/lifecycle.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { z as z4 } from "zod";
 var deleteConfirmation = z4.object({
   siteId: z4.string().min(1),
@@ -3493,7 +3773,7 @@ function registerLifecycleTools(server, baseCtx) {
       try {
         const ctx = withProjectDir(baseCtx, args.projectDir);
         const site = requireSiteFile(ctx);
-        const operationId = args.operationId ?? randomUUID2();
+        const operationId = args.operationId ?? randomUUID3();
         if (args.action === "preview") {
           const preview = await ctx.client.previewDeleteSite(site.siteId, site.credential, {
             operationId
@@ -3568,14 +3848,13 @@ function registerBillingTools(server, baseCtx) {
     "plans",
     {
       description: "Return the authoritative Sakupa monthly plan catalog, exact limits, prices, catalog version and plan-change billing rules. This is read-only and does not require a site.",
-      inputSchema: { projectDir: projectDirInput },
+      inputSchema: {},
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
     },
-    async (args) => {
+    async () => {
       try {
-        const ctx = withProjectDir(baseCtx, args.projectDir);
-        const catalog = await ctx.client.getBillingPlanCatalog();
+        const catalog = await baseCtx.client.getBillingPlanCatalog();
         return structuredToolResult({
           schemaVersion: 1,
           outcome: "completed",
@@ -3663,14 +3942,18 @@ Workflow:
 5. support (subscribed sites) opens a support ticket; report sends a
    sanitized diagnostic report after the user explicitly confirms it.
 
-Project directory contract: ONE directory = ONE site (its .sakupa/site.json holds the
-binding). projectDir is REQUIRED on EVERY tool call \u2014 always pass the absolute path of
-the user's PROJECT ROOT, the SAME directory every time for the same project: the folder
-the user opened (for framework projects, where package.json lives \u2014 never the dist/out
-build folder). For deploy, ALWAYS pass outputDir separately as the exact path RELATIVE to
-projectDir (use "." when publishing the root); outputDir is required and may have ANY name,
-so inspect the current project and never infer it from a conventional folder name. The server
-NEVER guesses either directory: only you can see the user's actual workspace and build output.
+Project directory contract: before the first deploy or a new recovery, initialize the intended
+project root once with "npx -y @sakupa/mcp@latest init"; this creates a non-secret
+.sakupa/project.json marker after the user confirms the canonical path. ONE initialized root =
+ONE site. Project-bound tools require projectDir, but it is only a path locator: it may point to
+the root or any existing child directory. The site-independent plans tool and public_recovery
+portal do not require a local project. Sakupa resolves upward to its own marker and stores
+.sakupa/site.json only at that authoritative root; it never uses package.json, .git, framework
+names or output-directory names to guess. For deploy, ALWAYS pass outputDir separately as the
+exact path RELATIVE to the resolved root (use "." when publishing the root); outputDir is
+required and may have ANY name, so inspect the current project. If it differs from the last
+successful publish directory, show the old and new paths and obtain explicit confirmation
+before retrying with outputDirChangeConfirmed: true.
 After every deploy, TELL the user which environment it went to (deploy results carry an
 Explicit Environment line: TEST vs PRODUCTION). analyze, deploy, status,
 refresh and delete echo