@getmonoceros/workbench 1.5.3 → 1.6.0

package/dist/bin.js

@@ -274,9 +274,8 @@ var SOLUTION_NAME_RE = /^[A-Za-z0-9._-]+$/;
 var APT_PACKAGE_NAME_RE = /^[a-z0-9][a-z0-9.+-]*$/;
 var FEATURE_REF_RE = /^[a-z0-9.-]+(\/[a-z0-9._-]+)+:[a-z0-9._-]+$/;
 var INSTALL_URL_RE = /^https:\/\/[A-Za-z0-9.\-_~/:?#[\]@!&'()*+,;=%]+$/;
-var REPO_URL_RE = /^[A-Za-z0-9@:/+_~.#=&?-]+$/;
-var REPO_NAME_RE = /^[A-Za-z0-9._-]+$/;
-var REPO_BRANCH_RE = /^[A-Za-z0-9._/-]+$/;
+var REPO_URL_RE = /^https:\/\/[A-Za-z0-9@:/+_~.#=&?-]+$/;
+var REPO_PATH_RE = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
 var POSTGRES_URL_RE = /^postgres(ql)?:\/\//;
 var REGEX = {
   solutionName: SOLUTION_NAME_RE,
@@ -284,10 +283,20 @@ var REGEX = {
   featureRef: FEATURE_REF_RE,
   installUrl: INSTALL_URL_RE,
   repoUrl: REPO_URL_RE,
-  repoName: REPO_NAME_RE,
-  repoBranch: REPO_BRANCH_RE,
+  repoPath: REPO_PATH_RE,
   postgresUrl: POSTGRES_URL_RE
 };
+var PROVIDER_VALUES = [
+  "github",
+  "gitlab",
+  "bitbucket",
+  "gitea"
+];
+var KNOWN_PROVIDER_HOSTS = {
+  "github.com": "github",
+  "gitlab.com": "gitlab",
+  "bitbucket.org": "bitbucket"
+};
 var CONFIG_SCHEMA_VERSION = 1;
 var FeatureOptionValueSchema = z.union([
   z.string(),
@@ -301,23 +310,39 @@ var FeatureEntrySchema = z.object({
   ),
   options: z.record(z.string(), FeatureOptionValueSchema).optional()
 });
+var GitUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().min(3).regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, "Invalid email")
+});
 var RepoEntrySchema = z.object({
   url: z.string().regex(
     REPO_URL_RE,
-    "Invalid repo URL. Use HTTPS or SSH/git@ form; no shell metacharacters."
+    "Invalid repo URL. Only HTTPS URLs are supported (https://...). SSH-style URLs (git@host:..., ssh://...) are not in scope \u2014 see ADR 0006."
   ),
-  name: z.string().regex(
-    REPO_NAME_RE,
-    "Invalid repo name. Folder name must match /^[A-Za-z0-9._-]+$/."
+  path: z.string().regex(
+    REPO_PATH_RE,
+    "Invalid repo path. Use letters/digits/'._-', forward slashes for nested folders, no leading or trailing slash."
+  ).refine(
+    (p) => !p.split("/").some((seg) => seg === ".." || seg === "."),
+    'Repo path segments cannot be "." or "..".'
   ).optional(),
-  branch: z.string().regex(
-    REPO_BRANCH_RE,
-    "Invalid branch name. Must match /^[A-Za-z0-9._/-]+$/."
-  ).optional()
-});
-var GitUserSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().min(3).regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, "Invalid email")
+  // Per-repo git identity override. Falls back to the container-level
+  // `git.user` (which itself falls back to the host's
+  // `git config --global` at apply time). Useful when a single
+  // container clones multiple repos that need different committer
+  // identities — e.g. work GitHub org vs personal projects.
+  git: z.object({
+    user: GitUserSchema.optional()
+  }).optional(),
+  // Provider hint for the pre-flight credential check. For the three
+  // canonical hosts (github.com / gitlab.com / bitbucket.org) the
+  // provider is auto-detected and this field is unnecessary. For any
+  // other host (self-hosted GitLab on a custom domain, Gitea, …) the
+  // builder MUST declare the provider so apply can suggest the right
+  // CLI setup (`glab auth login --hostname <host>` etc.) when
+  // credentials are missing. Enforced at apply pre-flight, not at
+  // parse time — see ADR 0006.
+  provider: z.enum(PROVIDER_VALUES).optional()
 });
 var ExternalServicesSchema = z.object({
   postgres: z.string().regex(
@@ -567,8 +592,7 @@ var APT_PACKAGE_NAME_RE2 = /^[a-z0-9][a-z0-9.+-]*$/;
 var FEATURE_REF_RE2 = /^[a-z0-9.-]+(\/[a-z0-9._-]+)+:[a-z0-9._-]+$/;
 var INSTALL_URL_RE2 = /^https:\/\/[A-Za-z0-9.\-_~/:?#[\]@!&'()*+,;=%]+$/;
 var REPO_URL_RE2 = /^[A-Za-z0-9@:/+_~.#=&?-]+$/;
-var REPO_NAME_RE2 = /^[A-Za-z0-9._-]+$/;
-var REPO_BRANCH_RE2 = /^[A-Za-z0-9._/-]+$/;
+var REPO_PATH_RE2 = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
 function deriveRepoName(url) {
   const lastSep = Math.max(url.lastIndexOf("/"), url.lastIndexOf(":"));
   const tail = url.slice(lastSep + 1);
@@ -621,29 +645,29 @@ function validateOptions(opts) {
       );
     }
   }
-  const seenRepoNames = /* @__PURE__ */ new Set();
+  const seenRepoPaths = /* @__PURE__ */ new Set();
   for (const repo of opts.repos ?? []) {
     if (!REPO_URL_RE2.test(repo.url)) {
       throw new Error(
         `Invalid repo URL: ${JSON.stringify(repo.url)}. Use HTTPS or SSH/git@ form; no shell metacharacters.`
       );
     }
-    if (!REPO_NAME_RE2.test(repo.name)) {
+    if (!REPO_PATH_RE2.test(repo.path)) {
       throw new Error(
-        `Invalid repo name: ${JSON.stringify(repo.name)}. Folder name must match ${REPO_NAME_RE2}.`
+        `Invalid repo path: ${JSON.stringify(repo.path)}. Use letters/digits/'._-', forward slashes for nested folders, no leading or trailing slash.`
       );
     }
-    if (repo.branch !== void 0 && !REPO_BRANCH_RE2.test(repo.branch)) {
+    if (repo.path.split("/").some((seg) => seg === ".." || seg === ".")) {
       throw new Error(
-        `Invalid branch name: ${JSON.stringify(repo.branch)}. Must match ${REPO_BRANCH_RE2}.`
+        `Invalid repo path: ${JSON.stringify(repo.path)}. Path segments cannot be "." or "..".`
       );
     }
-    if (seenRepoNames.has(repo.name)) {
+    if (seenRepoPaths.has(repo.path)) {
       throw new Error(
-        `Duplicate repo name: ${JSON.stringify(repo.name)}. Each projects/<name> folder must be unique \u2014 pass --name to disambiguate.`
+        `Duplicate repo path: ${JSON.stringify(repo.path)}. Each projects/<path> folder must be unique \u2014 pass --path to disambiguate.`
       );
     }
-    seenRepoNames.add(repo.name);
+    seenRepoPaths.add(repo.path);
   }
 }
 function normalizeOptions(opts) {
@@ -658,9 +682,7 @@ function normalizeOptions(opts) {
   ) : void 0;
   const installUrls = opts.installUrls ? [...new Set(opts.installUrls)] : void 0;
   const repos = opts.repos ? Array.from(
-    new Map(
-      opts.repos.map((r) => [`${r.url}
${r.name}
${r.branch ?? ""}`, r])
-    ).values()
+    new Map(opts.repos.map((r) => [`${r.url}
${r.path}`, r])).values()
   ) : void 0;
   return {
     name: opts.name,
@@ -676,19 +698,6 @@ function normalizeOptions(opts) {
 function needsCompose(opts) {
   return opts.services.length > 0;
 }
-var SSH_AGENT_TARGET = "/ssh-agent";
-var GIT_SSH_COMMAND = "ssh -o StrictHostKeyChecking=accept-new";
-function buildRepoAuthMounts() {
-  return [
-    `source=\${localEnv:SSH_AUTH_SOCK},target=${SSH_AGENT_TARGET},type=bind`
-  ];
-}
-function buildRepoAuthEnv() {
-  return {
-    SSH_AUTH_SOCK: SSH_AGENT_TARGET,
-    GIT_SSH_COMMAND
-  };
-}
 function resolveFeatures(opts) {
   const resolved = [];
   for (const langSpec of opts.languages) {
@@ -807,8 +816,6 @@ function buildDevcontainerJson(opts) {
       );
     }
   }
-  const wantsRepoAuth = (opts.repos?.length ?? 0) > 0;
-  const repoAuthEnv = wantsRepoAuth ? { containerEnv: buildRepoAuthEnv() } : {};
   if (needsCompose(opts)) {
     return {
       name: opts.name,
@@ -819,14 +826,10 @@ function buildDevcontainerJson(opts) {
       remoteUser: "node",
       forwardPorts: [3e3, 4e3],
       postCreateCommand: ".devcontainer/post-create.sh",
-      ...featuresField ?? {},
-      ...repoAuthEnv
+      ...featuresField ?? {}
     };
   }
-  const mounts = [
-    ...wantsRepoAuth ? buildRepoAuthMounts() : [],
-    ...homeMounts
-  ];
+  const mounts = [...homeMounts];
   const mountsField = mounts.length > 0 ? { mounts } : {};
   return {
     name: opts.name,
@@ -836,8 +839,7 @@ function buildDevcontainerJson(opts) {
     runArgs: ["--cap-add=NET_ADMIN"],
     forwardPorts: [3e3, 4e3],
     postCreateCommand: ".devcontainer/post-create.sh",
-    ...featuresField ?? {},
-    ...repoAuthEnv
+    ...featuresField ?? {}
   };
 }
 function buildComposeYaml(opts) {
@@ -859,13 +861,6 @@ function buildComposeYaml(opts) {
       lines.push(`      - ../home/${sub}:/home/node/${sub}`);
     }
   }
-  const wantsRepoAuth = (opts.repos?.length ?? 0) > 0;
-  if (wantsRepoAuth) {
-    lines.push(`      - \${SSH_AUTH_SOCK:-/dev/null}:${SSH_AGENT_TARGET}`);
-    lines.push("    environment:");
-    lines.push(`      SSH_AUTH_SOCK: ${SSH_AGENT_TARGET}`);
-    lines.push(`      GIT_SSH_COMMAND: "${GIT_SSH_COMMAND}"`);
-  }
   for (const svcId of opts.services) {
     const def = SERVICE_CATALOG[svcId];
     if (!def) continue;
@@ -887,10 +882,11 @@ function buildComposeYaml(opts) {
 function buildCodeWorkspaceJson(opts) {
   const folders = [{ path: "." }];
   const sortedRepos = [...opts.repos ?? []].sort(
-    (a, b) => a.name.localeCompare(b.name)
+    (a, b) => a.path.localeCompare(b.path)
   );
   for (const repo of sortedRepos) {
-    folders.push({ path: `projects/${repo.name}`, name: repo.name });
+    const label = repo.path.split("/").pop() ?? repo.path;
+    folders.push({ path: `projects/${repo.path}`, name: label });
   }
   return { folders };
 }
@@ -957,22 +953,34 @@ function buildPostCreateScript(opts) {
     lines.push(
       "",
       "# Repos managed by `monoceros add-repo`. Each entry is cloned",
-      "# into `projects/<name>/` if (and only if) the directory does",
+      "# into `projects/<path>/` if (and only if) the directory does",
       "# not exist yet. Existing project subfolders are left alone so",
-      "# local changes survive `monoceros apply` rebuilds.",
+      "# local changes survive `monoceros apply` rebuilds. Nested",
+      "# `<path>` (e.g. apps/web) is created via `mkdir -p` before the",
+      "# clone so the parent directories exist.",
       "mkdir -p projects"
     );
     for (const repo of opts.repos) {
-      const branchFlag = repo.branch ? ` --branch ${repo.branch}` : "";
-      const branchLabel = repo.branch ? ` (branch: ${repo.branch})` : "";
+      const parent = repo.path.includes("/") ? repo.path.slice(0, repo.path.lastIndexOf("/")) : null;
+      if (parent) {
+        lines.push(`mkdir -p "projects/${parent}"`);
+      }
       lines.push(
-        `if [ ! -d "projects/${repo.name}" ]; then`,
-        `  echo "\u2192 Cloning ${repo.name} from ${repo.url}${branchLabel}\u2026"`,
-        `  git clone${branchFlag} "${repo.url}" "projects/${repo.name}"`,
+        `if [ ! -d "projects/${repo.path}" ]; then`,
+        `  echo "\u2192 Cloning ${repo.path} from ${repo.url}\u2026"`,
+        `  git clone "${repo.url}" "projects/${repo.path}"`,
         `else`,
-        `  echo "\u2192 projects/${repo.name} already exists, skipping clone"`,
+        `  echo "\u2192 projects/${repo.path} already exists, skipping clone"`,
         `fi`
       );
+      if (repo.gitUser) {
+        const safeName = repo.gitUser.name.replace(/"/g, '\\"');
+        const safeEmail = repo.gitUser.email.replace(/"/g, '\\"');
+        lines.push(
+          `git -C "projects/${repo.path}" config user.name "${safeName}"`,
+          `git -C "projects/${repo.path}" config user.email "${safeEmail}"`
+        );
+      }
     }
   }
   return lines.join("\n") + "\n";
@@ -1123,25 +1131,56 @@ function addFeatureToDoc(doc, ref, options = {}) {
 }
 function addRepoToDoc(doc, repo) {
   const seq = ensureSeq(doc, "repos");
-  const repoName = repo.name ?? deriveRepoName(repo.url);
   for (const item of seq.items) {
     if (!isMap(item)) continue;
     const url = item.get("url");
     if (url !== repo.url) continue;
-    const existingName = item.get("name");
-    const effectiveName = typeof existingName === "string" ? existingName : deriveRepoName(url);
-    const existingBranch = item.get("branch");
-    if (effectiveName === repoName && (existingBranch ?? void 0) === (repo.branch ?? void 0)) {
+    const existingPath = item.get("path");
+    const effectivePath = typeof existingPath === "string" ? existingPath : deriveRepoName(url);
+    if (effectivePath !== repo.path) continue;
+    const existingGit = item.get("git", true);
+    const existingUser = existingGit && isMap(existingGit) ? existingGit.get("user", true) : null;
+    const existingName = existingUser && isMap(existingUser) ? existingUser.get("name") : null;
+    const existingEmail = existingUser && isMap(existingUser) ? existingUser.get("email") : null;
+    const existingGitUser = typeof existingName === "string" && typeof existingEmail === "string" ? { name: existingName, email: existingEmail } : void 0;
+    const sameGitUser = (existingGitUser?.name ?? null) === (repo.gitUser?.name ?? null) && (existingGitUser?.email ?? null) === (repo.gitUser?.email ?? null);
+    const existingProvider = item.get("provider");
+    const sameProvider = (typeof existingProvider === "string" ? existingProvider : null) === (repo.provider ?? null);
+    if (sameGitUser && sameProvider) {
       return false;
     }
+    if (repo.gitUser) {
+      const gitMap = new YAMLMap();
+      const userMap = new YAMLMap();
+      userMap.set("name", repo.gitUser.name);
+      userMap.set("email", repo.gitUser.email);
+      gitMap.set("user", userMap);
+      item.set("git", gitMap);
+    } else {
+      item.delete("git");
+    }
+    if (repo.provider) {
+      item.set("provider", repo.provider);
+    } else {
+      item.delete("provider");
+    }
+    return true;
   }
   const entry2 = new YAMLMap();
   entry2.set("url", repo.url);
-  if (repo.name !== void 0 && repo.name !== deriveRepoName(repo.url)) {
-    entry2.set("name", repo.name);
+  if (repo.path !== deriveRepoName(repo.url)) {
+    entry2.set("path", repo.path);
+  }
+  if (repo.gitUser) {
+    const gitMap = new YAMLMap();
+    const userMap = new YAMLMap();
+    userMap.set("name", repo.gitUser.name);
+    userMap.set("email", repo.gitUser.email);
+    gitMap.set("user", userMap);
+    entry2.set("git", gitMap);
   }
-  if (repo.branch !== void 0) {
-    entry2.set("branch", repo.branch);
+  if (repo.provider) {
+    entry2.set("provider", repo.provider);
   }
   seq.add(entry2);
   return true;
@@ -1174,16 +1213,16 @@ function removeFeatureFromDoc(doc, ref) {
   pruneEmptySeq(doc, "features");
   return true;
 }
-function removeRepoFromDoc(doc, urlOrName) {
+function removeRepoFromDoc(doc, urlOrPath) {
   const seq = doc.get("repos", true);
   if (!seq || !isSeq(seq)) return false;
   const idx = seq.items.findIndex((item) => {
     if (!isMap(item)) return false;
     const url = item.get("url");
-    if (url === urlOrName) return true;
-    const name = item.get("name");
-    const effectiveName = typeof name === "string" ? name : typeof url === "string" ? deriveRepoName(url) : void 0;
-    return effectiveName === urlOrName;
+    if (url === urlOrPath) return true;
+    const path13 = item.get("path");
+    const effectivePath = typeof path13 === "string" ? path13 : typeof url === "string" ? deriveRepoName(url) : void 0;
+    return effectivePath === urlOrPath;
   });
   if (idx < 0) return false;
   seq.items.splice(idx, 1);
@@ -1225,21 +1264,65 @@ function runAddAptPackages(input) {
   }
   return mutate(input, (doc) => addAptPackagesToDoc(doc, input.packages));
 }
-function runAddRepo(input) {
+async function runAddRepo(input) {
   const url = input.url.trim();
   if (url.length === 0) {
     throw new Error(
       "Missing repo URL. Usage: monoceros add-repo <containername> <url>."
     );
   }
-  const name = (input.repoName ?? deriveRepoName(url)).trim();
+  const path13 = (input.path ?? deriveRepoName(url)).trim();
+  const hasName = typeof input.gitName === "string" && input.gitName.trim().length > 0;
+  const hasEmail = typeof input.gitEmail === "string" && input.gitEmail.trim().length > 0;
+  if (hasName !== hasEmail) {
+    throw new Error(
+      "--git-name and --git-email must be set together. Pass both, or neither."
+    );
+  }
+  const explicitProvider = normalizeProvider(input.provider);
+  let host;
+  try {
+    host = url.startsWith("https://") ? new URL(url).hostname : void 0;
+  } catch {
+    host = void 0;
+  }
+  const canonical = host ? KNOWN_PROVIDER_HOSTS[host.toLowerCase()] : void 0;
+  if (host && !canonical && !explicitProvider) {
+    throw new Error(
+      `Host '${host}' is not a canonical Git provider Monoceros can auto-detect (github.com / gitlab.com / bitbucket.org). Pass --provider=github|gitlab|bitbucket so the credential-helper hints know which CLI to suggest.`
+    );
+  }
+  if (canonical && explicitProvider && explicitProvider !== canonical) {
+    throw new Error(
+      `--provider=${explicitProvider} contradicts host '${host}' (auto-detected as ${canonical}). Drop --provider for canonical hosts, or fix the value.`
+    );
+  }
+  const providerToWrite = !canonical && explicitProvider ? explicitProvider : void 0;
   const entry2 = {
     url,
-    name,
-    ...input.branch !== void 0 ? { branch: input.branch } : {}
+    path: path13,
+    ...hasName && hasEmail ? {
+      gitUser: {
+        name: input.gitName.trim(),
+        email: input.gitEmail.trim()
+      }
+    } : {},
+    ...providerToWrite ? { provider: providerToWrite } : {}
   };
   return mutate(input, (doc) => addRepoToDoc(doc, entry2));
 }
+function normalizeProvider(raw) {
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return void 0;
+  const lowered = trimmed.toLowerCase();
+  if (!PROVIDER_VALUES.includes(lowered)) {
+    throw new Error(
+      `Invalid --provider value: ${JSON.stringify(raw)}. Allowed: ${PROVIDER_VALUES.join(", ")}.`
+    );
+  }
+  return lowered;
+}
 function runAddFromUrl(input) {
   const url = input.url.trim();
   if (url.length === 0) {
@@ -1551,7 +1634,7 @@ var addRepoCommand = defineCommand4({
   meta: {
     name: "add-repo",
     group: "edit",
-    description: "Add a git repo to the container config. Cloned into projects/<folder>/ on container build. Idempotent \u2014 existing project subfolders are left alone. Folder name derived from URL by default; override with --as."
+    description: "Add a git repo to the container config. Cloned into projects/<path>/ on container build. Idempotent \u2014 existing project subfolders are left alone. Destination path derived from URL by default; override with --path (supports nested subfolders like apps/web). Branches/PRs are git-level concerns: clone, then `git checkout` inside the container."
   },
   args: {
     name: {
@@ -1564,13 +1647,21 @@ var addRepoCommand = defineCommand4({
       description: "Git URL (HTTPS or SSH/git@ form). E.g. https://github.com/foo/bar.git, git@github.com:foo/bar.git.",
       required: true
     },
-    as: {
+    path: {
+      type: "string",
+      description: "Destination under projects/. Subfolders via `/` (e.g. apps/web). Default: URL-derived single segment (bar.git \u2192 bar)."
+    },
+    "git-name": {
       type: "string",
-      description: "Folder name under projects/. Default: derived from URL (e.g. bar.git \u2192 bar)."
+      description: "Per-repo git committer name. Overrides the container-level git.user.name for this repo only. Pair with --git-email."
     },
-    branch: {
+    "git-email": {
       type: "string",
-      description: "Specific branch to clone (default: repo default branch)."
+      description: "Per-repo git committer email. Overrides the container-level git.user.email for this repo only. Pair with --git-name."
+    },
+    provider: {
+      type: "string",
+      description: "Git provider for credential-helper guidance: github | gitlab | bitbucket. Required when the URL host is not github.com, gitlab.com, or bitbucket.org \u2014 Monoceros uses this to suggest the right CLI (gh / glab / Atlassian token) on missing credentials."
     },
     yes: {
       type: "boolean",
@@ -1584,8 +1675,10 @@ var addRepoCommand = defineCommand4({
       const result = await runAddRepo({
         name: args.name,
         url: args.url,
-        ...typeof args.as === "string" ? { repoName: args.as } : {},
-        ...typeof args.branch === "string" ? { branch: args.branch } : {},
+        ...typeof args.path === "string" ? { path: args.path } : {},
+        ...typeof args["git-name"] === "string" ? { gitName: args["git-name"] } : {},
+        ...typeof args["git-email"] === "string" ? { gitEmail: args["git-email"] } : {},
+        ...typeof args.provider === "string" ? { provider: args.provider } : {},
         yes: args.yes
       });
       process.exit(result.status === "aborted" ? 1 : 0);
@@ -1804,11 +1897,13 @@ function solutionConfigToCreateOptions(config, featureDefaults = {}) {
   if (config.repos.length > 0) {
     result.repos = config.repos.map((r) => ({
       url: r.url,
-      // `name` is optional in the yml (derived from URL on apply),
-      // required in CreateOptions; the caller derives it via
-      // `deriveRepoName` when undefined.
-      name: r.name ?? deriveRepoName(r.url),
-      ...r.branch !== void 0 ? { branch: r.branch } : {}
+      // `path` is optional in the yml; CreateOptions requires it.
+      // When the yml omits `path`, fall back to the URL-derived
+      // single-segment default (`https://.../foo.git` → `foo`),
+      // which lands the clone at `projects/foo/`.
+      path: r.path ?? deriveRepoName(r.url),
+      ...r.git?.user ? { gitUser: { name: r.git.user.name, email: r.git.user.email } } : {},
+      ...r.provider ? { provider: r.provider } : {}
     }));
   }
   return result;
@@ -2020,7 +2115,10 @@ async function runStart(opts) {
   const logger = opts.logger ?? { info: (msg) => consola8.info(msg) };
   const spawnFn = opts.spawn ?? spawnDevcontainer;
   logger.info(`Bringing devcontainer up at ${opts.root}\u2026`);
-  return spawnFn(["up", "--workspace-folder", opts.root], opts.root);
+  return spawnFn(
+    ["up", "--workspace-folder", opts.root, "--mount-workspace-git-root=false"],
+    opts.root
+  );
 }
 async function runContainerCycle(root, opts) {
   const { hasCompose, logger } = opts;
@@ -2054,7 +2152,13 @@ async function runContainerCycle(root, opts) {
   logger.info(`Recreating image-mode devcontainer at ${root}\u2026`);
   const spawnFn = opts.devcontainerSpawn ?? spawnDevcontainer;
   return spawnFn(
-    ["up", "--workspace-folder", root, "--remove-existing-container"],
+    [
+      "up",
+      "--workspace-folder",
+      root,
+      "--mount-workspace-git-root=false",
+      "--remove-existing-container"
+    ],
     root
   );
 }
@@ -2089,7 +2193,13 @@ import path6 from "path";
 var realGitCredentialFill = (input) => {
   return new Promise((resolve, reject) => {
     const child = spawn3("git", ["credential", "fill"], {
-      stdio: ["pipe", "pipe", "inherit"]
+      stdio: ["pipe", "pipe", "inherit"],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_ASKPASS: "",
+        SSH_ASKPASS: ""
+      }
     });
     let stdout = "";
     child.stdout.on("data", (chunk) => {
@@ -2101,16 +2211,135 @@ var realGitCredentialFill = (input) => {
     child.stdin.end();
   });
 };
+function resolveProvider(host, explicit) {
+  const canonical = KNOWN_PROVIDER_HOSTS[host.toLowerCase()];
+  if (canonical) return canonical;
+  return explicit ?? "unknown";
+}
 function uniqueHttpsHosts(repos) {
-  const hosts = /* @__PURE__ */ new Set();
+  const byHost = /* @__PURE__ */ new Map();
   for (const repo of repos) {
     if (!repo.url.startsWith("https://")) continue;
+    let host;
     try {
-      hosts.add(new URL(repo.url).hostname);
+      host = new URL(repo.url).hostname;
     } catch {
+      continue;
     }
+    if (byHost.has(host)) continue;
+    byHost.set(host, { host, provider: resolveProvider(host, repo.provider) });
+  }
+  return [...byHost.values()];
+}
+function installCommandForOS(opts) {
+  switch (process.platform) {
+    case "darwin":
+      return cyan2(opts.brew);
+    case "win32":
+      return cyan2(opts.winget);
+    default:
+      if (opts.linuxBrew) return cyan2(opts.linuxBrew);
+      return `See ${opts.linuxDocsUrl} for package instructions.`;
+  }
+}
+function providerSetupHint(host, provider) {
+  if (provider === "github") {
+    const isSaas = host.toLowerCase() === "github.com";
+    const hostArg = isSaas ? "" : ` --hostname ${host}`;
+    const install = installCommandForOS({
+      brew: "brew install gh",
+      winget: "winget install --id GitHub.cli",
+      linuxDocsUrl: "https://github.com/cli/cli#installation"
+    });
+    return {
+      title: `${host} \u2014 GitHub`,
+      body: [
+        "Install the GitHub CLI:",
+        install,
+        "",
+        "Then run once:",
+        cyan2(`gh auth login${hostArg}`),
+        cyan2(`gh auth setup-git${hostArg}`),
+        "",
+        "`gh auth login` walks through OAuth in your browser.",
+        "`gh auth setup-git` wires gh into git as a credential helper."
+      ].join("\n")
+    };
   }
-  return [...hosts];
+  if (provider === "gitlab") {
+    const isSaas = host.toLowerCase() === "gitlab.com";
+    const hostArg = isSaas ? "" : ` --hostname ${host}`;
+    const install = installCommandForOS({
+      brew: "brew install glab",
+      winget: "winget install --id GLab.GLab",
+      linuxBrew: "brew install glab",
+      linuxDocsUrl: "https://gitlab.com/gitlab-org/cli#installation"
+    });
+    return {
+      title: `${host} \u2014 GitLab`,
+      body: [
+        "Install the GitLab CLI (glab):",
+        install,
+        "",
+        "Then run once:",
+        cyan2(`glab auth login${hostArg}`),
+        "",
+        "Choose `HTTPS` when asked for git-protocol, then accept",
+        '"Authenticate Git with your GitLab credentials" \u2014 glab',
+        "configures itself as the git credential helper."
+      ].join("\n")
+    };
+  }
+  if (provider === "bitbucket") {
+    const isCloud = host.toLowerCase() === "bitbucket.org";
+    if (isCloud) {
+      return {
+        title: `${host} \u2014 Bitbucket Cloud`,
+        body: [
+          "Bitbucket has no first-party CLI for git-credentials, so this",
+          "is a manual one-time setup. Generate an Atlassian API token at",
+          "https://id.atlassian.com/manage-profile/security/api-tokens",
+          "",
+          "Then store it via your OS credential helper:",
+          cyan2(
+            `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-atlassian-email>\\npassword=<token>\\n'`
+          )
+        ].join("\n")
+      };
+    }
+    return {
+      title: `${host} \u2014 Bitbucket Data Center`,
+      body: [
+        "Bitbucket has no first-party CLI for git-credentials, so this",
+        "is a manual one-time setup. Generate a personal HTTP access",
+        `token in your Bitbucket UI: profile picture (top right on ${host})`,
+        "\u2192 Manage account \u2192 HTTP access tokens \u2192 Create token. Give it",
+        "at least repo-read + repo-write scopes for the repos you need.",
+        "",
+        "Then store it via your OS credential helper:",
+        cyan2(
+          `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-bitbucket-username>\\npassword=<token>\\n'`
+        )
+      ].join("\n")
+    };
+  }
+  return {
+    title: `${host} \u2014 Gitea`,
+    body: [
+      "Gitea has no first-party CLI helper for git-credentials (the",
+      "`tea` CLI logs into its own config, not into your git credential",
+      "helper), so this is a manual one-time setup. Generate an access",
+      `token in your Gitea UI: profile picture (top right on ${host}) \u2192`,
+      'Settings \u2192 Applications \u2192 "Generate New Token". Give it at',
+      "least the `read:repository` scope (add `write:repository` if you",
+      "need push from the container).",
+      "",
+      "Then store it via your OS credential helper:",
+      cyan2(
+        `git credential approve <<< $'protocol=https\\nhost=${host}\\nusername=<your-gitea-username>\\npassword=<token>\\n'`
+      )
+    ].join("\n")
+  };
 }
 function parseCredentialFillOutput(output) {
   const result = {};
@@ -2129,17 +2358,26 @@ function formatCredentialLine(host, username, password) {
   const encPass = encodeURIComponent(password);
   return `https://${encUser}:${encPass}@${host}`;
 }
-async function collectGitCredentials(devContainerRoot, repos, options = {}) {
+async function collectGitCredentials(devContainerRoot, hosts, options = {}) {
   const credsDir = path6.join(devContainerRoot, ".monoceros");
   const credentialsPath = path6.join(credsDir, "git-credentials");
-  const hosts = uniqueHttpsHosts(repos);
   const spawnFn = options.spawn ?? realGitCredentialFill;
   const logger = options.logger ?? { info: () => {
   }, warn: () => {
   } };
   const lines = [];
-  let hostsSkipped = 0;
-  for (const host of hosts) {
+  const perHost = [];
+  for (const { host, provider } of hosts) {
+    if (provider === "unknown") {
+      perHost.push({
+        host,
+        provider: "github",
+        // placeholder — never rendered because pre-flight already bailed
+        status: "no-credentials",
+        detail: "provider not declared (internal: should not reach here)"
+      });
+      continue;
+    }
     logger.info(`Fetching credentials for ${host} from host git\u2026`);
     const input = `protocol=https
 host=${host}
@@ -2149,28 +2387,31 @@ host=${host}
     try {
       result = await spawnFn(input);
     } catch (err) {
-      logger.warn(
-        `git credential fill not runnable for ${host} (${err instanceof Error ? err.message : String(err)}); skipping.`
-      );
-      hostsSkipped += 1;
+      const detail = err instanceof Error ? err.message : String(err);
+      perHost.push({ host, provider, status: "spawn-error", detail });
       continue;
     }
     if (result.exitCode !== 0) {
-      logger.warn(
-        `git credential fill exited ${result.exitCode} for ${host}; container clone will prompt.`
-      );
-      hostsSkipped += 1;
+      perHost.push({
+        host,
+        provider,
+        status: "non-zero-exit",
+        detail: `exit code ${result.exitCode}`
+      });
       continue;
     }
     const { username, password } = parseCredentialFillOutput(result.stdout);
     if (!username || !password) {
-      logger.warn(
-        `git credential fill returned no username/password for ${host}; container clone will prompt.`
-      );
-      hostsSkipped += 1;
+      perHost.push({
+        host,
+        provider,
+        status: "no-credentials",
+        detail: "host credential helper returned no username/password"
+      });
       continue;
     }
     lines.push(formatCredentialLine(host, username, password));
+    perHost.push({ host, provider, status: "ok", detail: "" });
   }
   await fs6.mkdir(credsDir, { recursive: true });
   await fs6.writeFile(
@@ -2182,19 +2423,204 @@ host=${host}
   );
   return {
     hostsWritten: lines.length,
-    hostsSkipped,
+    hostsSkipped: perHost.filter((p) => p.status !== "ok").length,
+    perHost,
     credentialsPath
   };
 }
+function formatMissingCredentialsError(missing) {
+  if (missing.length === 1) {
+    const m = missing[0];
+    const hint = providerSetupHint(m.host, m.provider);
+    return [
+      `Missing Git credentials: ${hint.title}`,
+      "",
+      hint.body,
+      "",
+      `Then re-run ${cyan2("monoceros apply")}.`
+    ].join("\n");
+  }
+  const lines = [
+    `Missing Git credentials for ${missing.length} hosts:`,
+    ""
+  ];
+  for (const m of missing) {
+    const hint = providerSetupHint(m.host, m.provider);
+    lines.push(hint.title);
+    lines.push("");
+    lines.push(hint.body);
+    lines.push("");
+  }
+  lines.push(`Then re-run ${cyan2("monoceros apply")}.`);
+  return lines.join("\n");
+}
+function formatUnknownProviderError(hosts) {
+  const sorted = [...new Set(hosts)].sort();
+  const lines = [
+    sorted.length === 1 ? `Unknown Git provider for host ${sorted[0]}.` : `Unknown Git provider for ${sorted.length} hosts: ${sorted.join(", ")}.`,
+    "",
+    "Monoceros auto-detects only github.com / gitlab.com / bitbucket.org.",
+    "For any other host (self-hosted GitLab, Gitea, Bitbucket Server, \u2026)",
+    "declare the provider explicitly in the yml. Edit the repo entry:",
+    "",
+    cyan2("  repos:"),
+    cyan2(`    - url: https://${sorted[0]}/\u2026`),
+    cyan2("      provider: gitlab   # or: github, bitbucket, gitea"),
+    "",
+    `Or re-add with ${cyan2("monoceros add-repo <name> <url> --provider=<github|gitlab|bitbucket|gitea>")}.`
+  ];
+  return lines.join("\n");
+}
 
-// src/devcontainer/identity.ts
+// src/devcontainer/repo-reachability.ts
 import { spawn as spawn4 } from "child_process";
+var realGitLsRemote = (url) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn4("git", ["ls-remote", "--heads", "--", url], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_ASKPASS: "",
+        SSH_ASKPASS: ""
+      }
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({ stdout, stderr, exitCode: code ?? 0 })
+    );
+  });
+};
+function classifyStderr(stderr) {
+  const s = stderr.toLowerCase();
+  if (s.includes("could not resolve host") || s.includes("name or service not known") || s.includes("temporary failure in name resolution") || s.includes("no address associated with hostname")) {
+    return "dns";
+  }
+  if (s.includes("repository not found") || s.includes("may not have access") || s.includes("no longer exists") || s.includes("don't have permission") || s.includes("could not be found") || s.includes("the requested url returned error: 404")) {
+    return "not-found-or-no-access";
+  }
+  if (s.includes("authentication failed") || s.includes("could not read username") || s.includes("incorrect username or password") || s.includes("the requested url returned error: 401") || s.includes("the requested url returned error: 403")) {
+    return "auth-failed";
+  }
+  return "unknown";
+}
+async function checkRepoReachability(repos, options = {}) {
+  const spawnFn = options.spawn ?? realGitLsRemote;
+  const results = [];
+  for (const repo of repos) {
+    let result;
+    try {
+      result = await spawnFn(repo.url);
+    } catch (err) {
+      results.push({
+        url: repo.url,
+        ok: false,
+        kind: "unknown",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
+    if (result.exitCode === 0) {
+      results.push({ url: repo.url, ok: true, detail: "" });
+      continue;
+    }
+    results.push({
+      url: repo.url,
+      ok: false,
+      kind: classifyStderr(result.stderr),
+      detail: result.stderr.trim()
+    });
+  }
+  return results;
+}
+function formatUnreachableReposError(failures) {
+  const byKind = /* @__PURE__ */ new Map();
+  for (const f of failures) {
+    const kind = f.kind ?? "unknown";
+    const list = byKind.get(kind) ?? [];
+    list.push(f);
+    byKind.set(kind, list);
+  }
+  const totalUrls = failures.length;
+  const lines = [
+    totalUrls === 1 ? `Cannot reach declared repo: ${failures[0].url}` : `Cannot reach ${totalUrls} declared repos:`,
+    ""
+  ];
+  const sectionOrder = [
+    "not-found-or-no-access",
+    "auth-failed",
+    "dns",
+    "unknown"
+  ];
+  for (const kind of sectionOrder) {
+    const entries = byKind.get(kind);
+    if (!entries || entries.length === 0) continue;
+    lines.push(headerForKind(kind));
+    for (const e of entries) {
+      lines.push(`  \u2022 ${e.url}`);
+    }
+    for (const advice of adviceForKind(kind)) {
+      lines.push(`    - ${advice}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Then re-run ${cyan2("monoceros apply")}.`);
+  return lines.join("\n");
+}
+function headerForKind(kind) {
+  switch (kind) {
+    case "not-found-or-no-access":
+      return "Repository not found (or your credentials don't grant access):";
+    case "auth-failed":
+      return "Authentication failed (credentials are present but rejected):";
+    case "dns":
+      return "Host unreachable (DNS / VPN / offline \u2014 git couldn't resolve the hostname):";
+    case "unknown":
+      return "Unrecognised git error:";
+  }
+}
+function adviceForKind(kind) {
+  switch (kind) {
+    case "not-found-or-no-access":
+      return [
+        "Re-check the URL for typos (case-sensitive on most hosts).",
+        "Verify the repo still exists / is not archived in a way that hides it.",
+        "Ensure your token covers this org / workspace and has read scope (GitHub: `repo`; GitLab: `read_repository`; Bitbucket: repo read)."
+      ];
+    case "auth-failed":
+      return [
+        "Token may be expired or revoked \u2014 regenerate it from the provider UI.",
+        "Re-run the provider CLI login (gh auth login / glab auth login) \u2014 Monoceros picks up the refreshed token on the next apply."
+      ];
+    case "dns":
+      return [
+        "Check your internet / VPN \u2014 corporate Git hosts often require VPN.",
+        "Verify the hostname spelling in the yml."
+      ];
+    case "unknown":
+      return [
+        "Run `git ls-remote <url>` manually on the host to see the raw error."
+      ];
+  }
+}
+
+// src/devcontainer/identity.ts
+import { spawn as spawn5 } from "child_process";
 import { promises as fs7 } from "fs";
 import path7 from "path";
 import { consola as consola9 } from "consola";
 var realGitConfigGet = (key) => {
   return new Promise((resolve, reject) => {
-    const child = spawn4("git", ["config", "--global", "--get", key], {
+    const child = spawn5("git", ["config", "--global", "--get", key], {
       stdio: ["ignore", "pipe", "inherit"]
     });
     let stdout = "";
@@ -2352,11 +2778,30 @@ ${sectionLine(label)}
     ...globalConfig?.defaults?.git?.user ? { defaults: globalConfig.defaults.git.user } : {},
     logger: idLogger
   });
-  if (createOpts.repos && createOpts.repos.some((r) => r.url.startsWith("https://"))) {
-    await collectGitCredentials(targetDir, createOpts.repos, {
+  const hostsToFetch = uniqueHttpsHosts(createOpts.repos ?? []);
+  const unknownProviderHosts = hostsToFetch.filter((h) => h.provider === "unknown").map((h) => h.host);
+  if (unknownProviderHosts.length > 0) {
+    throw new Error(formatUnknownProviderError(unknownProviderHosts));
+  }
+  if (hostsToFetch.length > 0) {
+    const credResult = await collectGitCredentials(targetDir, hostsToFetch, {
       ...opts.credentialsSpawn ? { spawn: opts.credentialsSpawn } : {},
       logger: idLogger
     });
+    const missing = credResult.perHost.filter((p) => p.status !== "ok");
+    if (missing.length > 0) {
+      throw new Error(formatMissingCredentialsError(missing));
+    }
+  }
+  const declaredRepos = createOpts.repos ?? [];
+  if (declaredRepos.length > 0) {
+    const reachability = await checkRepoReachability(declaredRepos, {
+      ...opts.reachabilitySpawn ? { spawn: opts.reachabilitySpawn } : {}
+    });
+    const unreachable = reachability.filter((r) => !r.ok);
+    if (unreachable.length > 0) {
+      throw new Error(formatUnreachableReposError(unreachable));
+    }
   }
   section("Scaffold");
   await fs8.mkdir(targetDir, { recursive: true });
@@ -2686,6 +3131,7 @@ import { consola as consola13 } from "consola";
 // src/init/index.ts
 import { existsSync as existsSync7, promises as fs10 } from "fs";
 import { consola as consola12 } from "consola";
+import { parseDocument as parseDocument3 } from "yaml";
 
 // src/init/components.ts
 import { existsSync as existsSync5, promises as fs9 } from "fs";
@@ -3183,6 +3629,37 @@ async function runInit(opts) {
     const components = resolveComponents(catalog, requested);
     text = generateComposedYml(opts.name, components, lookup);
   }
+  const repos = (opts.withRepo ?? []).map((u) => u.trim()).filter((u) => u.length > 0);
+  if (repos.length > 0) {
+    const offending = [];
+    for (const url of repos) {
+      let host;
+      try {
+        host = url.startsWith("https://") ? new URL(url).hostname : void 0;
+      } catch {
+        host = void 0;
+      }
+      if (!host || !KNOWN_PROVIDER_HOSTS[host.toLowerCase()]) {
+        offending.push(url);
+      }
+    }
+    if (offending.length > 0) {
+      throw new Error(
+        [
+          `--with-repo only supports github.com / gitlab.com / bitbucket.org URLs.`,
+          `These are not canonical: ${offending.join(", ")}`,
+          `For other hosts, run \`monoceros init <name>\` first, then`,
+          `\`monoceros add-repo <name> <url> --provider=github|gitlab|bitbucket\`.`
+        ].join("\n")
+      );
+    }
+    const doc = parseDocument3(text);
+    for (const url of repos) {
+      const path13 = deriveRepoName(url);
+      addRepoToDoc(doc, { url, path: path13 });
+    }
+    text = String(doc);
+  }
   await fs10.mkdir(containerConfigsDir(home), { recursive: true });
   await fs10.writeFile(dest, text, "utf8");
   const documented = requested.length === 0;
@@ -3219,14 +3696,21 @@ var initCommand = defineCommand9({
       type: "string",
       description: "Comma-separated list of component names to compose, e.g. 'node,postgres,github,claude'. Sub-components use a slash, e.g. 'atlassian/twg'. When omitted, init writes a documented default with every catalog component commented out.",
       required: false
+    },
+    "with-repo": {
+      type: "string",
+      description: "Git URL of a repo to clone into projects/ on first apply. Repeatable: pass --with-repo=URL1 --with-repo=URL2 for multiple repos. Folder name derived from URL (foo.git \u2192 projects/foo/); use `monoceros add-repo --path=...` post-init for subfolder paths.",
+      required: false
     }
   },
   async run({ args, rawArgs }) {
     try {
       const withList = collectWithList(args.with, rawArgs);
+      const withRepoList = collectWithRepoList(rawArgs);
       await runInit({
         name: args.name,
-        ...withList ? { with: withList } : {}
+        ...withList ? { with: withList } : {},
+        ...withRepoList.length > 0 ? { withRepo: withRepoList } : {}
       });
     } catch (err) {
       consola13.error(err instanceof Error ? err.message : String(err));
@@ -3234,6 +3718,22 @@ var initCommand = defineCommand9({
     }
   }
 });
+function collectWithRepoList(rawArgs) {
+  const urls = [];
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const t = rawArgs[i];
+    if (t === "--with-repo") {
+      const next = rawArgs[i + 1];
+      if (typeof next === "string" && !next.startsWith("-")) {
+        urls.push(next);
+        i += 1;
+      }
+    } else if (t.startsWith("--with-repo=")) {
+      urls.push(t.slice("--with-repo=".length));
+    }
+  }
+  return urls;
+}
 function collectWithList(withArg, rawArgs) {
   if (typeof withArg !== "string" || withArg.trim().length === 0) {
     return void 0;
@@ -3881,14 +4381,22 @@ async function runShell(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
   const upCode = await spawnFn(
-    ["up", "--workspace-folder", opts.root],
+    ["up", "--workspace-folder", opts.root, "--mount-workspace-git-root=false"],
     opts.root,
     { quiet: true }
   );
   if (upCode !== 0) return upCode;
-  return spawnFn(["exec", "--workspace-folder", opts.root, "bash"], opts.root, {
-    interactive: true
-  });
+  return spawnFn(
+    [
+      "exec",
+      "--workspace-folder",
+      opts.root,
+      "--mount-workspace-git-root=false",
+      "bash"
+    ],
+    opts.root,
+    { interactive: true }
+  );
 }
 function assertContainerExists(root) {
   if (!existsSync10(path12.join(root, ".devcontainer"))) {
@@ -3908,13 +4416,19 @@ async function runInContainer(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
   const upCode = await spawnFn(
-    ["up", "--workspace-folder", opts.root],
+    ["up", "--workspace-folder", opts.root, "--mount-workspace-git-root=false"],
     opts.root,
     { quiet: true }
   );
   if (upCode !== 0) return upCode;
   return spawnFn(
-    ["exec", "--workspace-folder", opts.root, ...opts.command],
+    [
+      "exec",
+      "--workspace-folder",
+      opts.root,
+      "--mount-workspace-git-root=false",
+      ...opts.command
+    ],
     opts.root,
     { interactive: true }
   );