appmaker-git-remote-origin-fixer 0.1.0 → 0.1.4

package/README.md

@@ -3,17 +3,22 @@
 A small recovery CLI that repairs a local git `origin` remote after a GitHub
 **organization migration**.
 
-When repositories are transferred from one GitHub organization to another and
-then deleted from the old one, every developer's local clone still points at the
-old remote — so `git push` fails. Run this tool once, after that first failed
-push, and it repoints `origin` at the new organization for you.
+When repositories are moved from one GitHub organization to another — and the old
+copy is then **deleted** or **archived** — every developer's local clone still
+points at the old remote, so `git push` fails. Run this tool once, after that
+first failed push, and it repoints `origin` at the new organization for you.
 
 ```
-git push                            # ❌ fails — repo no longer exists in the old org
+git push                            # ❌ fails — repo was moved out of the old org
 appmaker-git-remote-origin-fixer    # 🔧 diagnoses and fixes origin
 git push                            # ✅ works
 ```
 
+> **Who this is for:** the package ships with **Appmaker.xyz**'s migration
+> configuration by default, so Appmaker developers can just install and run it.
+> It is not Appmaker-specific, though — the migration rules are pure data, so any
+> team can reuse it by supplying their own config (see [Configuration](#configuration)).
+
 ## Install
 
 ```bash
@@ -31,6 +36,8 @@ appmaker-git-remote-origin-fixer [options]
 
   -c, --config <path>   Use a specific migrations config file
   -n, --dry-run         Diagnose only; do not modify the remote
+  -f, --force           Rewrite origin to the destination unconditionally,
+                        without checking the source or destination
   -h, --help            Show help
   -v, --version         Show version
 ```
@@ -44,25 +51,46 @@ Read origin URL  →  parse org + repo
 Is the org a "source" in the migration config?
        │  no → "No migration configured" → exit
        ▼ yes
-Is the repo still reachable in the SOURCE org?      (git ls-remote)
-       ├─ reachable      → "still exists, nothing to do"
-       ├─ no permission  → permission error
-       └─ not found ↓
-Is the repo reachable in the DESTINATION org?       (git ls-remote)
+What state is the repo in the SOURCE org?
+       ├─ healthy (push works)       → "still exists, nothing to do"
+       ├─ archived (read-only)       → migrate ↓
+       └─ deleted (not found)        → migrate ↓
+                                         │
+                                         ▼
+Is the repo reachable in the DESTINATION org?      (git ls-remote)
        ├─ reachable      → rewrite origin → "run git push"
        ├─ no permission  → "exists, contact admin" (remote left unchanged)
        └─ not found      → "not found in either org"
 ```
 
-Repository existence is verified with `git ls-remote` using your **existing git
-credentials** — no GitHub token or API access is required. The remote is only
-rewritten once the destination is confirmed reachable.
+Detection uses your **existing git credentials** — no GitHub token or API access:
+
+- **Existence** is checked with `git ls-remote` (a read).
+- **Archived/read-only** is detected with a `git push --dry-run` probe: it sends
+  nothing and creates nothing, but the server still reports if the repo is
+  archived. (An archived repo reads fine, so a read alone can't detect it.)
+
+The remote is only rewritten once the destination is confirmed reachable —
+**except** under `--force` (see below).
+
+> **Note:** detection is most reliable with **SSH remotes**
+> (`git@github.com:Org/repo.git`), where GitHub returns clear messages. Over
+> HTTPS without cached credentials git may be unable to determine state; in that
+> case the tool leaves your remote untouched.
+
+### `--force`
+
+GitHub reports a **private repo you don't have access to** exactly like a
+missing one ("Repository not found") — so the destination check can't see it,
+and the tool would refuse to switch. If you *know* the repo was migrated and you
+will get access, run with `--force`:
+
+```bash
+appmaker-git-remote-origin-fixer --force
+```
 
-> **Note:** verification is most reliable with **SSH remotes**
-> (`git@github.com:Org/repo.git`), where GitHub returns a clear
-> "Repository not found" for missing repos. Over HTTPS without cached
-> credentials, git may be unable to determine existence; in that case the tool
-> reports that it could not verify and leaves your remote untouched.
+`--force` rewrites `origin` to the destination **unconditionally**, skipping both
+the source and destination checks. The next `git push` is then the real test.
 
 ## Configuration
 
@@ -82,9 +110,10 @@ The config is resolved in this order (first found wins):
 1. `--config <path>`
 2. `./migrations.json` (current directory)
 3. `~/.appmaker-git-remote-origin-fixer.json` (per-user override)
-4. the `migrations.json` bundled with the package
+4. the `migrations.json` bundled with the package (Appmaker.xyz's mappings)
 
-To support a new migration, update the config — no code change needed.
+To support a new migration, update the config — no code change needed. Other
+teams can use the tool by overriding the config via any of options 1–3 above.
 
 ## Development
 

package/dist/cli.js

@@ -30,6 +30,10 @@ USAGE
 OPTIONS
   -c, --config <path>   Use a specific migrations config file.
   -n, --dry-run         Diagnose only; do not modify the remote.
+  -f, --force           Rewrite origin to the destination unconditionally,
+                        without checking the source or destination. Use when
+                        the source is archived, or the destination is private
+                        and you do not have access yet.
   -h, --help            Show this help.
   -v, --version         Show the version.
 `;
@@ -40,6 +44,7 @@ function main() {
             options: {
                 config: { type: "string", short: "c" },
                 "dry-run": { type: "boolean", short: "n" },
+                force: { type: "boolean", short: "f" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
             },
@@ -64,6 +69,7 @@ function main() {
         return run({
             configPath: values.config,
             dryRun: values["dry-run"],
+            force: values.force,
         });
     }
     catch (err) {

package/dist/git.d.ts

@@ -25,3 +25,18 @@ export declare function setOriginUrl(url: string): void;
  * can distinguish "missing" from "no permission".
  */
 export declare function probeRemote(url: string): ProbeResult;
+export type PushStatus = "writable" | "archived" | "forbidden" | "not_found" | "unknown";
+export interface PushProbeResult {
+    status: PushStatus;
+    detail: string;
+}
+/**
+ * Probe whether the current repo could PUSH to `url`, without actually pushing.
+ *
+ * A `git push --dry-run` of the current commit to a throwaway ref sends nothing
+ * and creates nothing, but GitHub still enforces archived/permission checks
+ * during negotiation — so this distinguishes a writable repo from one that is
+ * archived (read-only). Requires a local commit to push; if HEAD is unborn the
+ * probe is inconclusive ("unknown").
+ */
+export declare function probePushable(url: string): PushProbeResult;

package/dist/git.js

@@ -87,3 +87,54 @@ export function probeRemote(url) {
             process.env.GIT_TERMINAL_PROMPT = prevPrompt;
     }
 }
+/**
+ * Probe whether the current repo could PUSH to `url`, without actually pushing.
+ *
+ * A `git push --dry-run` of the current commit to a throwaway ref sends nothing
+ * and creates nothing, but GitHub still enforces archived/permission checks
+ * during negotiation — so this distinguishes a writable repo from one that is
+ * archived (read-only). Requires a local commit to push; if HEAD is unborn the
+ * probe is inconclusive ("unknown").
+ */
+export function probePushable(url) {
+    if (!runGit(["rev-parse", "--verify", "HEAD"]).ok) {
+        return { status: "unknown", detail: "no local commit to probe with" };
+    }
+    const prevPrompt = process.env.GIT_TERMINAL_PROMPT;
+    process.env.GIT_TERMINAL_PROMPT = "0";
+    try {
+        const result = runGit([
+            "push",
+            "--dry-run",
+            url,
+            "HEAD:refs/heads/__appmaker_origin_fixer_probe__",
+        ]);
+        if (result.ok)
+            return { status: "writable", detail: "" };
+        const stderr = result.stderr.toLowerCase();
+        // Check archived first: GitHub's archived error also contains phrases that
+        // match the not_found patterns below.
+        if (stderr.includes("archived") || stderr.includes("read-only") || stderr.includes("read only")) {
+            return { status: "archived", detail: result.stderr };
+        }
+        if (stderr.includes("permission") ||
+            stderr.includes("denied") ||
+            stderr.includes("not authorized") ||
+            stderr.includes("authentication failed") ||
+            stderr.includes("403")) {
+            return { status: "forbidden", detail: result.stderr };
+        }
+        if (stderr.includes("repository not found") ||
+            stderr.includes("not found") ||
+            stderr.includes("does not exist")) {
+            return { status: "not_found", detail: result.stderr };
+        }
+        return { status: "unknown", detail: result.stderr };
+    }
+    finally {
+        if (prevPrompt === undefined)
+            delete process.env.GIT_TERMINAL_PROMPT;
+        else
+            process.env.GIT_TERMINAL_PROMPT = prevPrompt;
+    }
+}

package/dist/index.d.ts

@@ -12,6 +12,12 @@ export interface RunOptions {
     configPath?: string;
     /** Diagnose only; never modify the remote. */
     dryRun?: boolean;
+    /**
+     * Skip the "does the source still exist?" check and switch to the
+     * destination regardless of source state (e.g. when the source repo is
+     * archived and read-only). The destination is still verified first.
+     */
+    force?: boolean;
 }
 /** Returns a process exit code. */
 export declare function run(options?: RunOptions): number;

package/dist/index.js

@@ -8,9 +8,37 @@
  *   5. Probe destination  -> found -> rewrite origin; else explain
  */
 import { loadConfig } from "./config.js";
-import { getOriginUrl, isGitRepo, probeRemote, setOriginUrl, } from "./git.js";
+import { getOriginUrl, isGitRepo, probePushable, probeRemote, setOriginUrl, } from "./git.js";
 import { parseRemote, rewriteOrg } from "./remote-url.js";
 import * as ui from "./ui.js";
+/**
+ * Verify the destination repo is reachable and, if so, rewrite origin to it.
+ * Shared by the normal flow and --force. Returns a process exit code.
+ */
+function switchToDestination(parsed, destOrg, originUrl, dryRun) {
+    const destUrl = rewriteOrg(parsed, destOrg);
+    const dest = probeRemote(destUrl);
+    if (dest.status === "reachable") {
+        if (dryRun) {
+            ui.info("(dry run) Would update origin:");
+            ui.info(`  ${originUrl}  ->  ${destUrl}`);
+            return 0;
+        }
+        setOriginUrl(destUrl);
+        ui.updated(destOrg, originUrl, destUrl);
+        return 0;
+    }
+    if (dest.status === "forbidden") {
+        ui.permissionDenied(destOrg, parsed.repo);
+        return 1;
+    }
+    if (dest.status === "unknown") {
+        ui.probeFailed(destUrl, dest.detail);
+        return 1;
+    }
+    // not_found
+    return -1; // caller decides the message (differs for force vs normal flow)
+}
 /** Returns a process exit code. */
 export function run(options = {}) {
     if (!isGitRepo()) {
@@ -33,10 +61,39 @@ export function run(options = {}) {
         ui.noMigration(parsed.org);
         return 0; // Not an error — just nothing to do.
     }
+    // --force: rewrite origin to the destination unconditionally, without
+    // probing either the source or the destination. Useful when the source is
+    // archived, or when the destination is private and the user has no access
+    // yet (GitHub reports those as "not found"). The destination is NOT verified.
+    if (options.force) {
+        const destUrl = rewriteOrg(parsed, destOrg);
+        if (options.dryRun) {
+            ui.info("(dry run) Would update origin:");
+            ui.info(`  ${originUrl}  ->  ${destUrl}`);
+            return 0;
+        }
+        setOriginUrl(destUrl);
+        ui.forcedUpdate(destOrg, originUrl, destUrl);
+        return 0;
+    }
     // Step 4 — is the repo still in the source org?
     const source = probeRemote(originUrl);
     if (source.status === "reachable") {
-        ui.stillExists(parsed.org, parsed.repo);
+        // Readable — but an archived repo also reads fine. Probe push capability to
+        // tell a healthy repo from an archived (read-only) one.
+        const push = probePushable(originUrl);
+        if (push.status === "archived") {
+            ui.archivedSource(parsed.org, parsed.repo, destOrg);
+            const code = switchToDestination(parsed, destOrg, originUrl, !!options.dryRun);
+            if (code === -1) {
+                // Archived source, but destination not reachable (e.g. private/no access).
+                ui.archivedDestNotFound(destOrg, parsed.repo);
+                return 1;
+            }
+            return code;
+        }
+        // Writable or inconclusive — treat as genuinely present, nothing to do.
+        ui.stillExists(parsed.org, parsed.repo, destOrg);
         return 0;
     }
     if (source.status === "forbidden") {
@@ -49,27 +106,11 @@ export function run(options = {}) {
     }
     // status === "not_found" -> continue to the destination.
     // Step 5 — is the repo in the destination org?
-    const destUrl = rewriteOrg(parsed, destOrg);
-    const dest = probeRemote(destUrl);
-    if (dest.status === "reachable") {
-        if (options.dryRun) {
-            ui.info("(dry run) Would update origin:");
-            ui.info(`  ${originUrl}  ->  ${destUrl}`);
-            return 0;
-        }
-        setOriginUrl(destUrl);
-        ui.updated(destOrg, originUrl, destUrl);
-        return 0;
-    }
-    if (dest.status === "forbidden") {
-        ui.permissionDenied(destOrg, parsed.repo);
-        return 1;
-    }
-    if (dest.status === "unknown") {
-        ui.probeFailed(destUrl, dest.detail);
+    const code = switchToDestination(parsed, destOrg, originUrl, !!options.dryRun);
+    if (code === -1) {
+        // Not found in either org.
+        ui.notFoundAnywhere(parsed.repo, [parsed.org, destOrg]);
         return 1;
     }
-    // Not found in either org.
-    ui.notFoundAnywhere(parsed.repo, [parsed.org, destOrg]);
-    return 1;
+    return code;
 }

package/dist/ui.d.ts

@@ -14,7 +14,13 @@ export declare function unparseableRemote(url: string): void;
 /** Step 2: no migration configured for this org. */
 export declare function noMigration(org: string): void;
 /** Step 3: repository still exists in the source org. */
-export declare function stillExists(org: string, repo: string): void;
+export declare function stillExists(org: string, repo: string, destOrg: string): void;
+/** Auto-detected: source repo is archived (read-only); migrating. */
+export declare function archivedSource(org: string, repo: string, destOrg: string): void;
+/** Auto-detected archived source, but the destination could not be reached. */
+export declare function archivedDestNotFound(destOrg: string, repo: string): void;
+/** --force: origin rewritten without verifying the destination. */
+export declare function forcedUpdate(destOrg: string, from: string, to: string): void;
 /** Step 3/4: permission denied on a repository. */
 export declare function permissionDenied(org: string, repo: string): void;
 /** Step 4: found in destination -> updated. */

package/dist/ui.js

@@ -41,9 +41,39 @@ export function noMigration(org) {
     info(`No migration configured for organization:\n\n  ${bold(org)}`);
 }
 /** Step 3: repository still exists in the source org. */
-export function stillExists(org, repo) {
+export function stillExists(org, repo, destOrg) {
     info(`${CHECK} Repository ${bold(`${org}/${repo}`)} still exists.`);
     info("No changes required.");
+    info("");
+    info(dim(`If your push still fails (e.g. the repo was archived), re-run with ` +
+        `--force to switch to ${destOrg} anyway.`));
+}
+/** Auto-detected: source repo is archived (read-only); migrating. */
+export function archivedSource(org, repo, destOrg) {
+    info(`${yellow("!")} Repository ${bold(`${org}/${repo}`)} is archived (read-only).`);
+    info(`Migrating origin to ${bold(destOrg)}...`);
+    info("");
+}
+/** Auto-detected archived source, but the destination could not be reached. */
+export function archivedDestNotFound(destOrg, repo) {
+    error(`Source is archived, but ${bold(`${destOrg}/${repo}`)} was not found.`);
+    info("It may be private and you may not have access yet.");
+    info(dim("If you are sure it exists there, re-run with --force to switch anyway."));
+}
+/** --force: origin rewritten without verifying the destination. */
+export function forcedUpdate(destOrg, from, to) {
+    info(`${CHECK} Updated origin to ${bold(destOrg)} ${dim("(forced — destination not verified)")}.`);
+    info("");
+    info(dim(`  ${from}`));
+    info(dim("  ↓"));
+    info(`  ${green(to)}`);
+    info("");
+    info(yellow("Note: the destination was not checked. If the repository does not"));
+    info(yellow("exist there, or you do not have access yet, your next push will fail."));
+    info("");
+    info("Please run:");
+    info("");
+    info(bold("  git push"));
 }
 /** Step 3/4: permission denied on a repository. */
 export function permissionDenied(org, repo) {

package/migrations.json

@@ -2,6 +2,7 @@
   "migrations": {
     "AppMakerHQ": "Appmaker-xyz",
     "AppMakerPartnersHQ": "Appmaker-Partners",
-    "TestorOrg": "TestorOrg2"
+    "Appmaker-xyz": "AppMakerHQ",
+    "Appmaker-Partners": "AppMakerPartnersHQ"
   }
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "appmaker-git-remote-origin-fixer",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Recovery CLI that repairs a local git origin remote after a GitHub organization migration.",
   "type": "module",
   "bin": {
-    "appmaker-git-remote-origin-fixer": "./dist/cli.js"
+    "appmaker-git-remote-origin-fixer": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -14,7 +14,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/cli.js",
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "prepublishOnly": "npm run build"