@myvillage/cli 2.19.0 → 2.21.0

package/README.md

@@ -26,6 +26,11 @@ myvillage init-game ./my-game
 # Deploy to the platform
 myvillage deploy
 
+# Share it with your team on Village Git (any folder, not just games)
+myvillage team create "Pollen Path"     # or: myvillage team link <project>
+myvillage team push -m "Add level 2"   # save a version and share it
+myvillage team pull                    # get your team's latest
+
 # Publish a PDF story book to the Read tab
 myvillage publish-book ./my-story.pdf
 ```
@@ -34,6 +39,7 @@ myvillage publish-book ./my-story.pdf
 
 - **Publish Story Books** — Upload a comic-style PDF; the platform turns it into pages for the muni Read tab, with MVT rewards for readers who finish.
 - **Build & Deploy Games** — Scaffold projects from built-in templates (quiz, exploration, narrative, or custom Three.js) and deploy to the M-UNI game platform.
+- **Team Projects** — Save versions of a game, app or any folder and share them with your village team on Village Git. No git install or GitHub account needed; `myvillage team --help` lists the commands.
 - **Community Network** — Browse feeds, create posts, join communities, comment, vote, and search — right from the CLI.
 - **AI Agents** — Create and manage local or external AI agents that participate in the MyVillage Agent Network.
 - **Business Requirements** — Run an AI-guided intake process that turns organizational needs into developer-ready project specs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {
@@ -41,6 +41,7 @@
     "commander": "^11.1.0",
     "conf": "^12.0.0",
     "inquirer": "^9.2.12",
+    "isomorphic-git": "^1.44.11",
     "jpeg-js": "^0.4.4",
     "music-metadata": "^11.14.0",
     "open": "^10.0.3",

package/src/commands/agent-credentials.js

@@ -18,7 +18,7 @@ import {
 // The villager connects the provider once in MyVillage Studio or at
 // myvillageproject.ai. These commands only manage the per-agent consent.
 
-const VALID_PROVIDERS = ['google', 'microsoft', 'zoom', 'slack'];
+const VALID_PROVIDERS = ['google', 'microsoft', 'zoom', 'slack', 'plaid'];
 
 // Human-facing labels keyed by the lowercase slug the CLI accepts.
 const PROVIDER_LABELS = {
@@ -26,6 +26,7 @@ const PROVIDER_LABELS = {
   microsoft: 'Microsoft 365 (Outlook mail, Calendar)',
   zoom: 'Zoom',
   slack: 'Slack (channels, messages, search — acts as you)',
+  plaid: 'Bank accounts via Plaid (balances, transactions — read only)',
 };
 
 function fail(message) {

package/src/commands/team.js

@@ -0,0 +1,274 @@
+/**
+ * `myvillage team` — team projects on Village Git, for any folder (a game, a
+ * web app, anything a team builds together). The same operations as Studio's
+ * team bar: save a version, share it, get the team's latest.
+ *
+ * Every subcommand takes `--dir` (default: the current folder) and `--json`
+ * (one JSON object on stdout: `{ ok: true, … }` or `{ ok: false, error, code? }`,
+ * and a non-zero exit code on failure), so scripts and agents can drive it.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { basename, join, resolve } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { brand, villageSpinner } from '../utils/brand.js';
+import { isAuthenticated } from '../utils/auth.js';
+import { getMyVillages } from '../utils/village-resolver.js';
+import { TeamGitError } from '../utils/team-git.js';
+import { createTeamRepo, getTeamGitCredentials, listTeamRepos, teamGit } from '../utils/team-git-api.js';
+
+const projectDir = (options) => resolve(options.dir || process.cwd());
+
+/**
+ * Runs one team operation: checks sign-in, shows a spinner (or nothing with
+ * --json), and prints the result with `print` or the error.
+ */
+async function run(options, label, fn, print) {
+  const json = !!options.json;
+  const fail = (error, extra = {}) => {
+    process.exitCode = 1;
+    if (json) {
+      console.log(JSON.stringify({ ok: false, error, ...extra }));
+      return;
+    }
+    console.log(chalk.red(`  ✗ ${error}`));
+    for (const f of extra.files ?? []) console.log(brand.teal(`    ${f}`));
+  };
+
+  if (!isAuthenticated()) return fail("Sign in to MyVillage first: run 'myvillage login'.");
+
+  const spinner = json ? null : villageSpinner(label).start();
+  let result;
+  try {
+    result = await fn();
+  } catch (err) {
+    spinner?.stop();
+    if (err instanceof TeamGitError) return fail(err.message, { code: err.code, files: err.files });
+    return fail(err?.message ?? String(err));
+  }
+  spinner?.stop();
+  if (json) console.log(JSON.stringify({ ok: true, ...result }));
+  else print(result);
+}
+
+function printCommands(commands = []) {
+  if (commands.length) console.log(brand.teal(`  ran: ${commands.join(' && ')}`));
+}
+
+function shortOid(oid) {
+  return oid ? oid.slice(0, 7) : '';
+}
+
+/** A friendly name for the folder's first version: the game/app title, else the folder name. */
+function projectTitle(dir) {
+  for (const file of ['myvillage.json', 'package.json']) {
+    const p = join(dir, file);
+    if (!existsSync(p)) continue;
+    try {
+      const data = JSON.parse(readFileSync(p, 'utf8'));
+      const title = data.myvillage?.title || data.title || data.name;
+      if (title) return title;
+    } catch {
+      /* unreadable: fall through */
+    }
+  }
+  return basename(dir);
+}
+
+/**
+ * A folder can join a team project only if it exists and has no git history
+ * of its own. Checked before `create` makes anything on the server.
+ */
+function assertCanLink(dir) {
+  if (!existsSync(dir)) throw new Error(`${dir} doesn't exist.`);
+  if (existsSync(join(dir, '.git'))) {
+    throw new TeamGitError(
+      'has-history',
+      'This folder already has its own git history. Make a copy without the .git folder, or link it to the team project it already belongs to.',
+    );
+  }
+}
+
+/** Finds a team project by clone URL, `org/name` or `name`. */
+async function findTeamRepo(query) {
+  const repos = await listTeamRepos();
+  const q = query.trim().toLowerCase().replace(/\.git$/, '');
+  const matches = repos.filter((r) => {
+    const url = r.cloneUrl.toLowerCase().replace(/\.git$/, '');
+    return url === q || `${r.org}/${r.name}`.toLowerCase() === q || r.name.toLowerCase() === q;
+  });
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    throw new Error(`More than one team project is called "${query}": ${matches.map((r) => `${r.org}/${r.name}`).join(', ')}. Use org/name.`);
+  }
+  throw new Error(`No team project "${query}" in your villages. See them with 'myvillage team projects'.`);
+}
+
+/** The village to start a project in: --village (id or name), your only village, or a prompt. */
+async function pickVillage(options) {
+  const villages = await getMyVillages();
+  if (!villages.length) throw new Error("You aren't in a village yet, so you can't start a team project.");
+  if (options.village) {
+    const v = options.village.trim().toLowerCase();
+    const match = villages.find((x) => x.id === options.village || x.name?.toLowerCase() === v);
+    if (!match) throw new Error(`You aren't in a village "${options.village}". Your villages: ${villages.map((x) => x.name).join(', ')}.`);
+    return match;
+  }
+  if (villages.length === 1) return villages[0];
+  if (options.json || options.yes) {
+    throw new Error(`Choose a village with --village. Your villages: ${villages.map((x) => `${x.name} (${x.id})`).join(', ')}.`);
+  }
+  const { id } = await inquirer.prompt([{
+    type: 'list',
+    name: 'id',
+    message: 'Which village is this team project for?',
+    choices: villages.map((x) => ({ name: x.name, value: x.id })),
+  }]);
+  return villages.find((x) => x.id === id);
+}
+
+// ── Commands ─────────────────────────────────────────────
+
+export async function teamProjectsCommand(options = {}) {
+  await run(options, 'Loading team projects...', async () => ({ projects: await listTeamRepos() }), ({ projects }) => {
+    if (!projects.length) {
+      console.log(brand.teal("  No team projects in your villages yet. Start one with 'myvillage team create <name>'."));
+      return;
+    }
+    console.log(chalk.bold('\n  Team projects\n'));
+    for (const p of projects) {
+      console.log(`  ${brand.gold(`${p.org}/${p.name}`)}  ${brand.teal(p.villageName)}`);
+      if (p.description) console.log(`    ${p.description}`);
+      console.log(brand.teal(`    ${p.cloneUrl}`));
+    }
+    console.log('');
+  });
+}
+
+export async function teamCreateCommand(name, options = {}) {
+  const dir = projectDir(options);
+  await run(options, 'Starting the team project...', async () => {
+    assertCanLink(dir);
+    const village = await pickVillage(options);
+    const project = await createTeamRepo({ villageId: village.id, name, description: options.description });
+    const linked = await teamGit.link(dir, project.cloneUrl, projectTitle(dir));
+    return { project, ...linked };
+  }, ({ project, commands }) => {
+    console.log(brand.green(`  ✓ Started ${project.org}/${project.name} in ${project.villageName} and shared this folder with it.`));
+    printCommands(commands);
+  });
+}
+
+export async function teamLinkCommand(project, options = {}) {
+  const dir = projectDir(options);
+  await run(options, 'Connecting to the team project...', async () => {
+    if (!existsSync(dir)) throw new Error(`${dir} doesn't exist.`);
+    const repo = await findTeamRepo(project);
+    const linked = await teamGit.link(dir, repo.cloneUrl, projectTitle(dir));
+    return { project: repo, ...linked };
+  }, ({ project: repo, commands }) => {
+    console.log(brand.green(`  ✓ This folder is now part of ${repo.org}/${repo.name}.`));
+    printCommands(commands);
+  });
+}
+
+export async function teamCloneCommand(project, dirArg, options = {}) {
+  await run(options, 'Downloading the team project...', async () => {
+    const repo = await findTeamRepo(project);
+    const dir = resolve(dirArg || join(process.cwd(), repo.name));
+    const { commands } = await teamGit.clone(repo.cloneUrl, dir);
+    return { project: repo, dir, commands };
+  }, ({ project: repo, dir, commands }) => {
+    console.log(brand.green(`  ✓ Downloaded ${repo.org}/${repo.name} to ${dir}`));
+    printCommands(commands);
+  });
+}
+
+export async function teamStatusCommand(options = {}) {
+  const dir = projectDir(options);
+  await run(options, 'Checking...', async () => ({ status: await teamGit.status(dir) }), ({ status }) => {
+    if (!status.linked) {
+      console.log(brand.teal("  This folder isn't part of a team project. Use 'myvillage team link <project>' or 'myvillage team create <name>'."));
+      return;
+    }
+    console.log(`\n  Team project: ${brand.gold(status.remoteUrl)}`);
+    if (status.lastVersion) {
+      console.log(`  Last version: ${status.lastVersion.message} ${brand.teal(`(${status.lastVersion.author}, ${shortOid(status.lastVersion.oid)})`)}`);
+    }
+    if (status.changes.length) {
+      console.log(`  Unsaved changes (${status.changes.length}):`);
+      for (const c of status.changes) console.log(brand.teal(`    ${c.change.padEnd(8)} ${c.path}`));
+    } else {
+      console.log('  No unsaved changes.');
+    }
+    console.log(status.unshared ? `  ${status.unshared} saved version(s) not shared yet.\n` : '  Everything saved is shared.\n');
+  });
+}
+
+export async function teamHistoryCommand(options = {}) {
+  const dir = projectDir(options);
+  const depth = options.limit ? parseInt(options.limit, 10) : 30;
+  await run(options, 'Loading versions...', async () => ({ versions: await teamGit.history(dir, depth) }), ({ versions }) => {
+    if (!versions.length) {
+      console.log(brand.teal('  No saved versions yet.'));
+      return;
+    }
+    for (const v of versions) {
+      console.log(`  ${brand.gold(shortOid(v.oid))}  ${v.message}  ${brand.teal(`${v.author}, ${new Date(v.when).toLocaleString()}`)}`);
+    }
+  });
+}
+
+export async function teamSaveCommand(options = {}) {
+  const dir = projectDir(options);
+  await run(options, 'Saving a version...', () => teamGit.saveVersion(dir, options.message), ({ version, commands }) => {
+    console.log(brand.green(`  ✓ Saved "${version.message}" (${shortOid(version.oid)}). Share it with 'myvillage team share'.`));
+    printCommands(commands);
+  });
+}
+
+export async function teamShareCommand(options = {}) {
+  const dir = projectDir(options);
+  await run(options, 'Sharing with your team...', () => teamGit.share(dir), ({ shared, commands }) => {
+    console.log(shared ? brand.green(`  ✓ Shared ${shared} version(s) with your team.`) : brand.teal('  Nothing new to share.'));
+    printCommands(commands);
+  });
+}
+
+export async function teamPushCommand(options = {}) {
+  const dir = projectDir(options);
+  await run(options, 'Saving and sharing...', () => teamGit.push(dir, options.message), ({ saved, shared, commands }) => {
+    if (saved) console.log(brand.green(`  ✓ Saved "${saved.message}" (${shortOid(saved.oid)}).`));
+    console.log(shared ? brand.green(`  ✓ Shared ${shared} version(s) with your team.`) : brand.teal('  Nothing new to share.'));
+    printCommands(commands);
+  });
+}
+
+export async function teamPullCommand(options = {}) {
+  if (options.mine && options.theirs) {
+    process.exitCode = 1;
+    console.log(chalk.red('  ✗ Choose --mine or --theirs, not both.'));
+    return;
+  }
+  const dir = projectDir(options);
+  const resolveWith = options.mine ? 'mine' : options.theirs ? 'theirs' : undefined;
+  await run(options, "Getting your team's latest...", () => teamGit.getLatest(dir, resolveWith ? { resolve: resolveWith } : {}), ({ updated, files, commands }) => {
+    if (!updated) console.log(brand.teal("  You already have your team's latest."));
+    else {
+      console.log(brand.green(`  ✓ Got your team's latest (${files.length} file(s) changed).`));
+      for (const f of files) console.log(brand.teal(`    ${f}`));
+    }
+    printCommands(commands);
+  });
+}
+
+/** Checks that this account can use Village Git, without touching any folder. */
+export async function teamWhoamiCommand(options = {}) {
+  await run(options, 'Checking Village Git...', async () => {
+    const c = await getTeamGitCredentials();
+    return { host: c.host, gitUsername: c.gitUsername, author: c.author };
+  }, ({ host, gitUsername, author }) => {
+    console.log(`  Village Git: ${brand.gold(host)}`);
+    console.log(`  You are ${brand.gold(gitUsername)} (commits as ${author.name} <${author.email}>)`);
+  });
+}

package/src/index.js

@@ -19,6 +19,19 @@ import { createGameCommand } from './commands/create-game.js';
 import { initGameCommand } from './commands/init-game.js';
 import { createCommand } from './commands/create-app.js';
 import { deployCommand } from './commands/deploy.js';
+import {
+  teamProjectsCommand,
+  teamCreateCommand,
+  teamLinkCommand,
+  teamCloneCommand,
+  teamStatusCommand,
+  teamHistoryCommand,
+  teamSaveCommand,
+  teamShareCommand,
+  teamPushCommand,
+  teamPullCommand,
+  teamWhoamiCommand,
+} from './commands/team.js';
 import { publishBookCommand } from './commands/publish-book.js';
 import { booksListCommand } from './commands/books.js';
 import { publishEpisodeCommand } from './commands/publish-episode.js';
@@ -676,17 +689,17 @@ export function run() {
     .description('List the MCP servers currently configured for an agent')
     .action(agentListMcpCommand);
 
-  // Per-agent OAuth credential grants (Google/Microsoft/Zoom). The villager
+  // Per-agent credential grants (Google/Microsoft/Zoom/Slack/Plaid). The villager
   // connects the provider once in the app/portal; these authorize a specific
   // agent to use it via the MyVillage MCP server. Tokens never touch the CLI.
   agentCmd
     .command('grant <name> <provider>')
-    .description('Authorize an agent to use a connected provider (google, microsoft, zoom)')
+    .description('Authorize an agent to use a connected provider (google, microsoft, zoom, slack, plaid)')
     .action(agentGrantCommand);
 
   agentCmd
     .command('revoke <name> <provider>')
-    .description('Revoke an agent\'s access to a provider (google, microsoft, zoom)')
+    .description('Revoke an agent\'s access to a provider (google, microsoft, zoom, slack, plaid)')
     .action(agentRevokeCredentialCommand);
 
   agentCmd
@@ -1120,6 +1133,84 @@ export function run() {
     .option('--json', 'Output raw JSON')
     .action(modelPredictCommand);
 
+  // ── Team projects (Village Git) ────────────────────────
+  const teamCmd = program
+    .command('team')
+    .description('Team projects on Village Git: save, share and get the latest of any folder');
+  const dirOpt = ['--dir <path>', 'Project folder (default: current folder)'];
+  const jsonOpt = ['--json', 'Output the result as JSON (non-interactive)'];
+  teamCmd
+    .command('projects')
+    .description("List the team projects in your villages")
+    .option(...jsonOpt)
+    .action(teamProjectsCommand);
+  teamCmd
+    .command('create <name>')
+    .description('Start a team project in your village and share this folder as its first version')
+    .option('--village <idOrName>', 'Village to start it in (default: your only village, or a prompt)')
+    .option('--description <text>', 'Short description of the project')
+    .option('-y, --yes', 'Non-interactive: never prompt')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamCreateCommand);
+  teamCmd
+    .command('link <project>')
+    .description('Connect this folder to an existing team project (name, org/name or clone URL) and share it')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamLinkCommand);
+  teamCmd
+    .command('clone <project> [dir]')
+    .description('Download a team project (default folder: ./<project name>)')
+    .option(...jsonOpt)
+    .action(teamCloneCommand);
+  teamCmd
+    .command('status')
+    .description('Show unsaved changes and versions not shared yet')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamStatusCommand);
+  teamCmd
+    .command('history')
+    .description('List saved versions')
+    .option('--limit <n>', 'How many versions to show (default 30)')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamHistoryCommand);
+  teamCmd
+    .command('save')
+    .description('Save a version of everything changed (git add -A && git commit)')
+    .option('-m, --message <text>', 'What changed')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamSaveCommand);
+  teamCmd
+    .command('share')
+    .description('Share saved versions with your team (git push)')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamShareCommand);
+  teamCmd
+    .command('push')
+    .description('Save a version if anything changed, then share it: one step for scripts and agents')
+    .option('-m, --message <text>', 'What changed')
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamPushCommand);
+  teamCmd
+    .command('pull')
+    .description("Get your team's latest (git pull); refuses while you have unsaved changes")
+    .option('--mine', 'Where you both changed the same lines, keep your side')
+    .option('--theirs', "Where you both changed the same lines, keep your teammate's side")
+    .option(...dirOpt)
+    .option(...jsonOpt)
+    .action(teamPullCommand);
+  teamCmd
+    .command('whoami')
+    .description('Check that your account can use Village Git')
+    .option(...jsonOpt)
+    .action(teamWhoamiCommand);
+
   // ── Fleet runner ───────────────────────────────────────
   const runnerCmd = program
     .command('runner')

package/src/utils/team-git-api.js

@@ -0,0 +1,59 @@
+/**
+ * Village Git through the signed-in MyVillage account: the credentials and
+ * team-project endpoints on ed-platform (`/api/v1/git/*`), plus the
+ * ready-to-use `teamGit` operations (team-git.js) wired to them.
+ */
+import { getApiClient } from './api.js';
+import { createTeamGit } from './team-git.js';
+
+export class TeamGitUnavailableError extends Error {}
+
+async function call(method, path, data) {
+  try {
+    const res = await getApiClient().request({ method, url: path, data });
+    return res.data;
+  } catch (err) {
+    const status = err.response?.status;
+    const body = err.response?.data;
+    const message = typeof body === 'object' && body ? body.error : undefined;
+    if (status === 401) throw new Error('Sign in to MyVillage first: run `myvillage login`.');
+    if (status === 503 || (status === 404 && !message)) {
+      throw new TeamGitUnavailableError("Team projects aren't available on this MyVillage server yet.");
+    }
+    if (status) throw new Error(message ?? `MyVillage answered ${status}.`);
+    throw err;
+  }
+}
+
+// Tokens last an hour; refresh with a few minutes to spare.
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+let cached = null;
+let inflight = null;
+
+/**
+ * A one-hour Village Git token for the signed-in villager:
+ * { host, username, password, expiresAt, author: { name, email }, gitUsername }.
+ */
+export async function getTeamGitCredentials(force = false) {
+  if (!force && cached && Date.parse(cached.expiresAt) - Date.now() > REFRESH_MARGIN_MS) return cached;
+  if (!inflight) {
+    inflight = call('post', '/git/credentials')
+      .then((c) => (cached = c))
+      .finally(() => {
+        inflight = null;
+      });
+  }
+  return inflight;
+}
+
+/** Team projects in the villager's villages. */
+export async function listTeamRepos() {
+  return (await call('get', '/git/repos')).repos;
+}
+
+/** Starts a team project in a village. Leads and Members can; Family can't. */
+export async function createTeamRepo({ villageId, name, description }) {
+  return (await call('post', '/git/repos', { villageId, name, description })).repo;
+}
+
+export const teamGit = createTeamGit((force) => getTeamGitCredentials(force));

package/src/utils/team-git.js

@@ -0,0 +1,410 @@
+/**
+ * Team version control on Village Git (the MyVillage-hosted Forgejo; see
+ * ed-platform docs/architecture/village-git.md) for any project folder: a
+ * game, a web app, or anything else a team builds together.
+ *
+ * Pure-JS git (isomorphic-git), so villagers never install git. Every
+ * operation also reports the equivalent git commands, so callers can show
+ * "ran: git commit -m …" and villagers learn the real thing.
+ *
+ * Friendly name → git:
+ *   Save a version        → git add -A && git commit
+ *   Share with team       → git push
+ *   Get team's latest     → git pull
+ *
+ * Ported from MyVillage Studio's cli-bridge team-git.ts, which writes the same
+ * .git layout. No chalk/inquirer here: Studio can import this in-process.
+ * This module only needs a credentials provider (team-git-api.js has the
+ * signed-in one), so it can be tested against any git HTTP server.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import git from 'isomorphic-git';
+import http from 'isomorphic-git/http/node';
+
+/**
+ * @typedef {{ username: string, password: string, author: { name: string, email: string } }} GitCredentials
+ * @typedef {(force?: boolean) => Promise<GitCredentials>} CredentialsProvider
+ *   `force` asks for fresh credentials (the server rejected the cached ones).
+ */
+
+/**
+ * Codes: not-linked | has-history | unsaved | nothing-to-save | behind | conflict | auth
+ */
+export class TeamGitError extends Error {
+  constructor(code, message, files = []) {
+    super(message);
+    this.code = code;
+    this.files = files;
+  }
+}
+
+const BRANCH = 'main';
+const REMOTE = 'origin';
+const REMOTE_REF = `refs/remotes/${REMOTE}/${BRANCH}`;
+
+/** Never shared: dependencies, build output, OS junk, Unity's regenerated folders. */
+const DEFAULT_IGNORES = ['node_modules/', 'dist/', '.DS_Store', 'Thumbs.db', '.env', '.env.*', 'Library/', 'Temp/', 'Logs/', 'obj/'];
+
+const NOT_LINKED = "This folder isn't part of a team project yet.";
+
+const quote = (s) => `"${s.replace(/(["\\$`])/g, '\\$1')}"`;
+
+/** @param {CredentialsProvider} getCredentials */
+export function createTeamGit(getCredentials) {
+  /** onAuth hooks for isomorphic-git: retry once with fresh credentials, then give up. */
+  function authHooks() {
+    let retried = false;
+    return {
+      onAuth: async () => {
+        const c = await getCredentials();
+        return { username: c.username, password: c.password };
+      },
+      onAuthFailure: async () => {
+        if (retried) return { cancel: true };
+        retried = true;
+        const c = await getCredentials(true);
+        return { username: c.username, password: c.password };
+      },
+    };
+  }
+
+  function wrapAuth(err) {
+    const code = err?.code;
+    if (code === 'UserCanceledError' || (code === 'HttpError' && /40[13]/.test(String(err.message)))) {
+      throw new TeamGitError('auth', "Village Git didn't let you in. You may no longer be on this team, or you need to sign in again.");
+    }
+    throw err;
+  }
+
+  async function isRepo(dir) {
+    try {
+      await git.resolveRef({ fs, dir, ref: 'HEAD' });
+      return true;
+    } catch {
+      return fs.existsSync(path.join(dir, '.git'));
+    }
+  }
+
+  async function remoteUrl(dir) {
+    if (!fs.existsSync(path.join(dir, '.git'))) return null;
+    return (await git.getConfig({ fs, dir, path: `remote.${REMOTE}.url` })) ?? null;
+  }
+
+  async function oid(dir, ref) {
+    try {
+      return await git.resolveRef({ fs, dir, ref });
+    } catch {
+      return null;
+    }
+  }
+
+  async function changes(dir) {
+    const matrix = await git.statusMatrix({ fs, dir });
+    const out = [];
+    // "Racy git": isomorphic-git trusts file stats (whole seconds + size), so a
+    // same-size edit in the same second as the last save looks unchanged. Like
+    // real git, re-check those files by content.
+    const indexFile = path.join(dir, '.git', 'index');
+    const indexSecond = fs.existsSync(indexFile) ? Math.floor(fs.statSync(indexFile).mtimeMs / 1000) : 0;
+    const head = await oid(dir, 'HEAD');
+    for (const [filepath, inHead, workdir] of matrix) {
+      if (inHead === 0 && workdir === 2) out.push({ path: filepath, change: 'added' });
+      else if (inHead === 1 && workdir === 2) out.push({ path: filepath, change: 'modified' });
+      else if (inHead === 1 && workdir === 0) out.push({ path: filepath, change: 'deleted' });
+      else if (inHead === 1 && workdir === 1 && head && (await racilyChanged(dir, head, filepath, indexSecond))) {
+        out.push({ path: filepath, change: 'modified' });
+      }
+    }
+    return out;
+  }
+
+  async function racilyChanged(dir, head, filepath, indexSecond) {
+    const abs = path.join(dir, filepath);
+    const stat = fs.statSync(abs, { throwIfNoEntry: false });
+    if (!stat || Math.floor(stat.mtimeMs / 1000) < indexSecond) return false;
+    const [{ oid: inWorkdir }, { oid: inHead }] = await Promise.all([
+      git.hashBlob({ object: fs.readFileSync(abs) }),
+      git.readBlob({ fs, dir, oid: head, filepath }),
+    ]);
+    return inWorkdir !== inHead;
+  }
+
+  async function countUnshared(dir) {
+    const local = await oid(dir, BRANCH);
+    if (!local) return 0;
+    const remote = await oid(dir, REMOTE_REF);
+    if (local === remote) return 0;
+    // Versions reachable from ours but not from the team's. After getting the
+    // team's latest, the log interleaves both sides, so check every entry.
+    const log = await git.log({ fs, dir, ref: BRANCH, depth: 100 });
+    let n = 0;
+    for (const entry of log) {
+      if (entry.oid === remote) continue;
+      const shared = remote ? await git.isDescendent({ fs, dir, oid: remote, ancestor: entry.oid, depth: -1 }).catch(() => false) : false;
+      if (!shared) n++;
+    }
+    return n;
+  }
+
+  async function lastVersion(dir) {
+    try {
+      const [entry] = await git.log({ fs, dir, ref: BRANCH, depth: 1 });
+      return entry ? toVersion(entry) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function toVersion(entry) {
+    return {
+      oid: entry.oid,
+      message: entry.commit.message.trim(),
+      author: entry.commit.author.name,
+      when: entry.commit.author.timestamp * 1000,
+    };
+  }
+
+  function ensureIgnores(dir) {
+    const file = path.join(dir, '.gitignore');
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const have = new Set(existing.split(/\r?\n/).map((l) => l.trim()));
+    const missing = DEFAULT_IGNORES.filter((l) => !have.has(l));
+    if (missing.length === 0) return;
+    const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+    const header = existing ? '' : '# Not shared with the team (added by MyVillage)\n';
+    fs.writeFileSync(file, `${existing}${prefix}${header}${missing.join('\n')}\n`);
+  }
+
+  async function fetchTeam(dir) {
+    try {
+      await git.fetch({ fs, http, dir, remote: REMOTE, ref: BRANCH, singleBranch: true, tags: false, ...authHooks() });
+    } catch (err) {
+      // An empty team project has no main yet; nothing to fetch.
+      if (err?.code === 'NotFoundError') return;
+      wrapAuth(err);
+    }
+  }
+
+  async function status(dir) {
+    const url = await remoteUrl(dir);
+    if (!url || !(await isRepo(dir))) {
+      return { linked: false, remoteUrl: url, changes: [], unshared: 0, lastVersion: null };
+    }
+    return {
+      linked: true,
+      remoteUrl: url,
+      changes: await changes(dir),
+      unshared: await countUnshared(dir),
+      lastVersion: await lastVersion(dir),
+    };
+  }
+
+  async function saveVersion(dir, message) {
+    if (!(await remoteUrl(dir))) throw new TeamGitError('not-linked', NOT_LINKED);
+    const pending = await changes(dir);
+    if (pending.length === 0) throw new TeamGitError('nothing-to-save', 'Nothing has changed since your last saved version.');
+    for (const c of pending) {
+      if (c.change === 'deleted') await git.remove({ fs, dir, filepath: c.path });
+      else await git.add({ fs, dir, filepath: c.path });
+    }
+    const { author } = await getCredentials();
+    const text = (message ?? '').trim() || 'Save a version';
+    const oidSaved = await git.commit({ fs, dir, message: text, author });
+    const [entry] = await git.log({ fs, dir, ref: oidSaved, depth: 1 });
+    return { version: toVersion(entry), commands: ['git add -A', `git commit -m ${quote(text)}`] };
+  }
+
+  async function share(dir) {
+    if (!(await remoteUrl(dir))) throw new TeamGitError('not-linked', NOT_LINKED);
+    await fetchTeam(dir);
+    const unshared = await countUnshared(dir);
+    if (unshared === 0) return { shared: 0, commands: [`git push ${REMOTE} ${BRANCH}`] };
+    try {
+      const res = await git.push({ fs, http, dir, remote: REMOTE, ref: BRANCH, ...authHooks() });
+      if (!res.ok) throw new Error(res.error ?? 'Push failed');
+    } catch (err) {
+      if (err?.code === 'PushRejectedError') {
+        throw new TeamGitError('behind', "Your team shared changes you don't have yet. Get the team's latest first, then share.");
+      }
+      wrapAuth(err);
+    }
+    return { shared: unshared, commands: [`git push ${REMOTE} ${BRANCH}`] };
+  }
+
+  /**
+   * Saves a version when anything changed, then shares everything not yet
+   * shared: one step for scripts and agents. `saved` is null when there was
+   * nothing new to save.
+   */
+  async function push(dir, message) {
+    let saved = null;
+    try {
+      saved = await saveVersion(dir, message);
+    } catch (err) {
+      if (!(err instanceof TeamGitError && err.code === 'nothing-to-save')) throw err;
+    }
+    const shared = await share(dir);
+    return {
+      saved: saved?.version ?? null,
+      shared: shared.shared,
+      commands: [...(saved?.commands ?? []), ...shared.commands],
+    };
+  }
+
+  /**
+   * Brings in the team's shared versions. Refuses while there are unsaved
+   * changes, so nothing of the villager's is ever overwritten. When both sides
+   * changed the same lines, returns the files unless `resolve` says whose wins.
+   *
+   * @param {{ resolve?: 'mine' | 'theirs' }} [opts]
+   */
+  async function getLatest(dir, opts = {}) {
+    if (!(await remoteUrl(dir))) throw new TeamGitError('not-linked', NOT_LINKED);
+    const pending = await changes(dir);
+    if (pending.length > 0) {
+      throw new TeamGitError('unsaved', 'Save a version first, so none of your work gets overwritten.', pending.map((c) => c.path));
+    }
+    const commands = [`git fetch ${REMOTE}`, `git merge ${REMOTE}/${BRANCH}`];
+    await fetchTeam(dir);
+    const local = await oid(dir, BRANCH);
+    const remote = await oid(dir, REMOTE_REF);
+    if (!remote || local === remote) return { updated: false, files: [], commands };
+    if (local && (await git.isDescendent({ fs, dir, oid: local, ancestor: remote, depth: -1 }))) {
+      return { updated: false, files: [], commands };
+    }
+
+    const before = local;
+    const { author } = await getCredentials();
+    try {
+      await git.merge({
+        fs,
+        dir,
+        ours: BRANCH,
+        theirs: REMOTE_REF,
+        author,
+        message: "Get team's latest",
+        ...(opts.resolve
+          ? {
+              mergeDriver: ({ contents }) => ({
+                cleanMerge: true,
+                mergedText: opts.resolve === 'mine' ? contents[1] : contents[2],
+              }),
+            }
+          : {}),
+      });
+    } catch (err) {
+      if (err?.code === 'MergeConflictError') {
+        throw new TeamGitError(
+          'conflict',
+          'You and a teammate changed the same part of these files. Choose whose changes to keep.',
+          err.data?.filepaths ?? [],
+        );
+      }
+      if (err?.code === 'MergeNotSupportedError') {
+        throw new TeamGitError('conflict', "You and a teammate changed the same files in ways that can't be combined automatically yet.");
+      }
+      throw err;
+    }
+    await git.checkout({ fs, dir, ref: BRANCH });
+    const after = await oid(dir, BRANCH);
+    const files = before && after ? await changedBetween(dir, before, after) : [];
+    if (opts.resolve) commands.push(`# kept ${opts.resolve === 'mine' ? 'your' : "your teammate's"} side where you both changed the same lines`);
+    return { updated: true, files, commands };
+  }
+
+  async function changedBetween(dir, a, b) {
+    const files = [];
+    await git.walk({
+      fs,
+      dir,
+      trees: [git.TREE({ ref: a }), git.TREE({ ref: b })],
+      map: async (filepath, [x, y]) => {
+        if (filepath === '.') return undefined;
+        const [tx, ty] = [await x?.type(), await y?.type()];
+        if (tx === 'tree' || ty === 'tree') return undefined;
+        if ((await x?.oid()) !== (await y?.oid())) files.push(filepath);
+        return undefined;
+      },
+    });
+    return files;
+  }
+
+  /**
+   * Connects an existing folder to a team project. The folder's files are
+   * kept; anything already in the project the folder doesn't have is added;
+   * then everything is saved and shared as the project's first version from
+   * this folder.
+   */
+  async function link(dir, cloneUrl, title) {
+    const existing = await remoteUrl(dir);
+    if (existing === cloneUrl) return { status: await status(dir), commands: [] };
+    if (existing || (await oid(dir, 'HEAD'))) {
+      throw new TeamGitError(
+        'has-history',
+        'This folder already has its own git history. Make a copy without the .git folder, or ask a Lead to start the team project from it.',
+      );
+    }
+
+    const commands = [
+      `git init -b ${BRANCH}`,
+      `git remote add ${REMOTE} ${cloneUrl}`,
+      `git fetch ${REMOTE}`,
+    ];
+    await git.init({ fs, dir, defaultBranch: BRANCH });
+    await git.setConfig({ fs, dir, path: `remote.${REMOTE}.url`, value: cloneUrl });
+    await git.setConfig({ fs, dir, path: `remote.${REMOTE}.fetch`, value: `+refs/heads/*:refs/remotes/${REMOTE}/*` });
+    await git.setConfig({ fs, dir, path: `branch.${BRANCH}.remote`, value: REMOTE });
+    await git.setConfig({ fs, dir, path: `branch.${BRANCH}.merge`, value: `refs/heads/${BRANCH}` });
+    ensureIgnores(dir);
+
+    await fetchTeam(dir);
+    const remote = await oid(dir, REMOTE_REF);
+    if (remote) {
+      // Start from the project's history without touching the folder's files…
+      await git.writeRef({ fs, dir, ref: `refs/heads/${BRANCH}`, value: remote, force: true });
+      // The index must match that history too, or the first save would drop the project's files.
+      for (const filepath of await git.listFiles({ fs, dir, ref: BRANCH })) {
+        await git.resetIndex({ fs, dir, filepath });
+      }
+      // …and bring in project files this folder doesn't have (e.g. its README).
+      const missing = [];
+      for (const [filepath, head, workdir] of await git.statusMatrix({ fs, dir })) {
+        if (head === 1 && workdir === 0) missing.push(filepath);
+      }
+      if (missing.length) await git.checkout({ fs, dir, ref: BRANCH, filepaths: missing, force: true });
+      commands.push(`git reset ${REMOTE}/${BRANCH}`);
+    }
+
+    const saved = await saveVersion(dir, `Add ${title} to the team project`);
+    const shared = await share(dir);
+    return { status: await status(dir), commands: [...commands, ...saved.commands, ...shared.commands] };
+  }
+
+  /** Downloads a team project into `dir` (which must not exist or be empty). */
+  async function clone(cloneUrl, dir) {
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0) {
+      throw new Error(`${dir} already has files in it. Choose an empty folder.`);
+    }
+    try {
+      await git.clone({ fs, http, dir, url: cloneUrl, ref: BRANCH, singleBranch: true, ...authHooks() });
+    } catch (err) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      wrapAuth(err);
+    }
+    await git.setConfig({ fs, dir, path: `branch.${BRANCH}.remote`, value: REMOTE });
+    await git.setConfig({ fs, dir, path: `branch.${BRANCH}.merge`, value: `refs/heads/${BRANCH}` });
+    return { commands: [`git clone ${cloneUrl}`] };
+  }
+
+  async function history(dir, depth = 30) {
+    if (!(await isRepo(dir))) return [];
+    try {
+      return (await git.log({ fs, dir, ref: BRANCH, depth })).map(toVersion);
+    } catch {
+      return [];
+    }
+  }
+
+  return { status, saveVersion, share, push, getLatest, link, clone, history };
+}

package/src/utils/templates.js

@@ -1147,6 +1147,7 @@ function generate2DGameAgents(name, gameType, orientation) {
     '    npm run dev      # local dev server, live reload',
     '    npm run build    # production build -> dist/ (must pass before deploy)',
     '    myvillage deploy # build, then upload + submit to MyVillage',
+    '    myvillage team push -m "what changed" # team projects: save a version + share it on Village Git',
     '',
     'Keep asset URLs relative (Vite `base: \'./\'`). The host serves the game from a sub-path, so absolute `/...` URLs will break.',
     '',
@@ -1241,6 +1242,7 @@ function generate3DGameAgents(name, type, orientation) {
     '    npm run dev      # local dev server, live reload',
     '    npm run build    # production build -> dist/ (must pass before deploy)',
     '    myvillage deploy # build, then upload + submit to MyVillage',
+    '    myvillage team push -m "what changed" # team projects: save a version + share it on Village Git',
     '',
     'Keep asset URLs relative (Vite `base: \'./\'`). The host serves from a sub-path, so absolute `/...` URLs break.',
     '',
@@ -1305,6 +1307,7 @@ function generateConvertedGameAgents(name, orientation) {
     '    npm run dev      # local dev server, live reload',
     '    npm run build    # production build -> dist/ (must pass before deploy)',
     '    myvillage deploy # build, then upload + submit to MyVillage',
+    '    myvillage team push -m "what changed" # team projects: save a version + share it on Village Git',
     '',
     'Keep asset URLs relative (Vite `base: \'./\'`). The host serves from a sub-path, so absolute `/...` URLs break.',
     '',