@ozyman42/ozy-cli 0.4.9-linux-x64.0 → 0.4.9

package/install.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "darwin-arm64",
+  "darwin-x64": "darwin-x64",
+  "linux-arm64": "linux-arm64",
+  "linux-x64": "linux-x64",
+  "win32-x64": "windows-x64"
+};
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": "@ozyman42/ozy-cli-darwin-arm64",
+  "darwin-x64": "@ozyman42/ozy-cli-darwin-x64",
+  "linux-arm64": "@ozyman42/ozy-cli-linux-arm64",
+  "linux-x64": "@ozyman42/ozy-cli-linux-x64",
+  "windows-x64": "@ozyman42/ozy-cli-windows-x64"
+};
+const PLATFORM_BINARIES = {
+  "darwin-arm64": "multi-call-binary",
+  "darwin-x64": "multi-call-binary",
+  "linux-arm64": "multi-call-binary",
+  "linux-x64": "multi-call-binary",
+  "windows-x64": "multi-call-binary.exe"
+};
+const COMMANDS = [
+  "ozy",
+  "ozy-signing-agent",
+  "ozy-ssh-keygen",
+  "ozy-virtual-security-key"
+];
+const BIN_DIR = "bin";
+const INSTALL_SCRIPT = "install.js";
+// Root install.js repairs command targets; bin launchers repair and then execute.
+const IS_INSTALL_SCRIPT = true;
+const WINDOWS_EXECUTABLE_SUFFIX = ".exe";
+const INSTALLED_JSON = "installed.json";
+
+const require = createRequire(import.meta.url);
+const launcherPath = fileURLToPath(import.meta.url);
+const launcherDir = dirname(launcherPath);
+const packageDir = IS_INSTALL_SCRIPT ? launcherDir : dirname(launcherDir);
+const commandTargetDir = join(packageDir, BIN_DIR);
+const rootInstallScriptPath = join(packageDir, INSTALL_SCRIPT);
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function currentPlatformKey() {
+  const platformKey = PLATFORM_MAP[`${process.platform}-${process.arch}`];
+  if (!platformKey) {
+    fail(`Unsupported platform: ${process.platform}-${process.arch}`);
+  }
+  return platformKey;
+}
+
+function currentPlatformPackageName() {
+  const platformKey = currentPlatformKey();
+  const packageName = PLATFORM_PACKAGES[platformKey];
+  if (!packageName) {
+    fail(`No platform package is configured for ${platformKey}`);
+  }
+  return packageName;
+}
+
+/**
+ * When a Jive library contains any number of CLIs (entrypoints or agents), then the base package
+ * will have an optional dependency for each possible architecture, with those platform-specific
+ * packages containing a platform build of the CLI.
+ * @returns the path to the platform binary and the exact version of the platform package.
+ */
+function currentPlatformPackage() {
+  const platformKey = currentPlatformKey();
+  const binaryFile = PLATFORM_BINARIES[platformKey];
+  if (!binaryFile) {
+    fail(`No platform binary is configured for ${platformKey}`);
+  }
+
+  const packageName = currentPlatformPackageName();
+  try {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`);
+    const packageDir = dirname(packageJsonPath);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return {
+      binaryPath: join(packageDir, binaryFile),
+      version: packageJson.version,
+    };
+  } catch (error) {
+    fail(`Could not resolve optional platform package ${packageName}. Reinstall dependencies for ${process.platform}-${process.arch}.`);
+  }
+}
+
+function commandTargetPath(command) {
+  const suffix = process.platform === "win32" ? WINDOWS_EXECUTABLE_SUFFIX : "";
+  return join(commandTargetDir, `${command}${suffix}`);
+}
+
+function installedJsonPath() {
+  return join(commandTargetDir, INSTALLED_JSON);
+}
+
+function windowsTargetsAreCurrent(version) {
+  if (process.platform !== "win32") return false;
+  if (!COMMANDS.every((command) => existsSync(commandTargetPath(command)))) return false;
+
+  try {
+    const installed = JSON.parse(readFileSync(installedJsonPath(), "utf-8"));
+    return installed.version === version;
+  } catch {
+    return false;
+  }
+}
+
+function linkOrCopyFirstExecutable(sourcePath, targetPath) {
+  mkdirSync(dirname(targetPath), { recursive: true });
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp${process.platform === "win32" ? WINDOWS_EXECUTABLE_SUFFIX : ""}`;
+  rmSync(tempPath, { force: true });
+
+  try {
+    try {
+      linkSync(sourcePath, tempPath);
+    } catch {
+      copyFileSync(sourcePath, tempPath);
+    }
+
+    chmodSync(tempPath, 0o755);
+    rmSync(targetPath, { force: true });
+    renameSync(tempPath, targetPath);
+  } finally {
+    rmSync(tempPath, { force: true });
+  }
+}
+
+function hardLinkCommandTarget(sourcePath, targetPath) {
+  if (sourcePath === targetPath) return;
+
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp${process.platform === "win32" ? WINDOWS_EXECUTABLE_SUFFIX : ""}`;
+  rmSync(tempPath, { force: true });
+
+  try {
+    linkSync(sourcePath, tempPath);
+    chmodSync(tempPath, 0o755);
+    rmSync(targetPath, { force: true });
+    renameSync(tempPath, targetPath);
+  } finally {
+    rmSync(tempPath, { force: true });
+  }
+}
+
+function repairCommandTargets() {
+  const platformPackage = currentPlatformPackage();
+
+  if (windowsTargetsAreCurrent(platformPackage.version)) {
+    return;
+  }
+
+  const firstTargetPath = commandTargetPath(COMMANDS[0]);
+  linkOrCopyFirstExecutable(platformPackage.binaryPath, firstTargetPath);
+
+  for (const command of COMMANDS.slice(1)) {
+    hardLinkCommandTarget(firstTargetPath, commandTargetPath(command));
+  }
+
+  if (process.platform === "win32") {
+    writeFileSync(installedJsonPath(), `${JSON.stringify({ version: platformPackage.version }, null, 2)}\n`);
+  }
+}
+
+function runExecutable(executablePath) {
+  const result = spawnSync(executablePath, process.argv.slice(2), { stdio: "inherit" });
+
+  if (result.error) {
+    fail(result.error.message);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function removeInstallScript() {
+  try {
+    rmSync(rootInstallScriptPath, { force: true });
+    // TODO: should we also remove the postinstall script line from package.json?
+  } catch {
+    // Cleanup is best-effort; failing to remove install.js should not fail package installation.
+  }
+}
+
+repairCommandTargets();
+removeInstallScript();
+if (!IS_INSTALL_SCRIPT) {
+  const commandName = basename(launcherPath);
+  runExecutable(commandTargetPath(commandName));
+}

package/package.json

@@ -1,17 +1,8 @@
 {
   "name": "@ozyman42/ozy-cli",
-  "version": "0.4.9-linux-x64.0",
-  "type": "module",
-  "os": [
-    "linux"
-  ],
-  "cpu": [
-    "x64"
-  ],
-  "files": [
-    "multi-call-binary"
-  ],
+  "version": "0.4.9",
   "description": "Tools for setting up new packages, configuring with git & npm",
+  "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,5 +11,61 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./entrypoints": null,
+    "./entrypoints/*": null,
+    "./agents": null,
+    "./agents/*": null,
+    "./internal": null,
+    "./internal/*": null,
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist",
+    "src",
+    "bin",
+    "install.js"
+  ],
+  "scripts": {
+    "postinstall": "node ./install.js"
+  },
+  "bin": {
+    "ozy": "./bin/ozy",
+    "ozy-signing-agent": "./bin/ozy-signing-agent",
+    "ozy-ssh-keygen": "./bin/ozy-ssh-keygen",
+    "ozy-virtual-security-key": "./bin/ozy-virtual-security-key"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "^4.0.0-beta.70",
+    "@ozyman42/interactive-cli-select": "^0.2.0",
+    "bip39": "^3.1.0",
+    "bs58": "^6.0.0",
+    "commander": "^13.1.0",
+    "effect": "4.0.0-beta.70",
+    "effective-modules": "0.3.1-effect4",
+    "expand-tilde": "^2.0.2",
+    "friendly-words": "^1.3.1",
+    "ssh-config": "^5.0.3",
+    "zod": "^3.24.2"
+  },
+  "optionalDependencies": {
+    "@ozyman42/ozy-cli-darwin-arm64": "npm:@ozyman42/ozy-cli@0.4.9-darwin-arm64.0",
+    "@ozyman42/ozy-cli-darwin-x64": "npm:@ozyman42/ozy-cli@0.4.9-darwin-x64.0",
+    "@ozyman42/ozy-cli-linux-arm64": "npm:@ozyman42/ozy-cli@0.4.9-linux-arm64.0",
+    "@ozyman42/ozy-cli-linux-x64": "npm:@ozyman42/ozy-cli@0.4.9-linux-x64.0",
+    "@ozyman42/ozy-cli-windows-x64": "npm:@ozyman42/ozy-cli@0.4.9-windows-x64.0"
   }
 }

package/src/commands/git/hosts.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { makeCommand } from "@/common/command";
+import { log } from "@/common/log";
+import { commonModules } from "@/modules/common";
+import { SSHConfigImpl } from "@/modules/common/ssh-config/impl";
+
+export const hosts = makeCommand('hosts', 'show all configured github.com SSH hosts', () =>
+  Effect.gen(function* () {
+    const sshConfig = yield* commonModules.SSHConfig;
+    const config = yield* sshConfig.getSSHConfig();
+    const gitHosts: string[] = [];
+    for (const host in config) {
+      if (config[host]!.HostName === 'github.com') {
+        gitHosts.push(host);
+      }
+    }
+    log('Available hosts:');
+    gitHosts.forEach(host => { log(` - ${host}`); });
+  }).pipe(Effect.provide(SSHConfigImpl.Layer))
+);

package/src/commands/git/index.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import { setup } from './setup';
+import { hosts } from './hosts';
+
+export const git = new Command('git')
+  .summary('setup git in repo for verified commits');
+
+[setup, hosts]
+  .forEach(cmd => { git.addCommand(cmd) });

package/src/commands/git/setup.ts

@@ -0,0 +1,182 @@
+import { Command } from 'commander';
+import { Effect, Layer, Option, pipe } from 'effect';
+import { log } from '@/common/log';
+import { cliModules, type CLIModules } from '@/modules/cli';
+import { commonModules, CommonModules } from '@/modules/common';
+import { effunct, type EffectGen } from 'effective-modules';
+import { GitImpl } from '@/modules/cli/git/impl';
+import { GitHubImpl } from '@/modules/cli/github/impl';
+import { AgentClientImpl } from '@/modules/cli/agent-client/impl';
+import { OSPlatformImpl } from '@/modules/common/os-platform/impl';
+import { SSHConfigImpl } from '@/modules/common/ssh-config/impl';
+import { AGENT_SOCK_FILE_PATH, FUTURE_TOOL_NAME, STANDARD_REMOTE_PREFIX } from '../../common/constants';
+import { CredentialId } from '@/modules/common/crypto/impl';
+import { BunFileSystem } from "@effect/platform-bun";
+import type { GitUser } from '@/modules/cli/git/interface';
+
+type AllModules = CLIModules.Git | CLIModules.GitHub | CLIModules.AgentClient | CommonModules.SSHConfig;
+
+const GITHUB_CLIENT_ID = 'Ov23liKYxk1Ag7SsNhbP';
+const GITHUB_CLIENT_SECRET = 'e2901fbe93c591e7a53a903e70490ff87e998159';
+const OAUTH_SCOPES = 'read:user user:email write:ssh_signing_key write:public_key';
+const KEY_PREFIX = `${FUTURE_TOOL_NAME}-`;
+
+function parseCredentialIdFromTitle(title: string): Option.Option<string> {
+  const match = title.match(/\(([^)]+)\)$/);
+  if (!match) return Option.none();
+  return Option.some(match[1]!);
+}
+
+function baseKey(pubkey: string): string {
+  return pubkey.split(' ').slice(0, 2).join(' ');
+}
+
+export enum GitSetupError {
+  NotInGitRepositoryError = 'NotInGitRepositoryError',
+  NoRemoteOriginError = 'NoRemoteOriginError',
+  OAuthFailedError = 'OAuthFailedError',
+  GitHubUserFetchFailedError = 'GitHubUserFetchFailedError',
+  RepoAccessDeniedError = 'RepoAccessDeniedError',
+  MultipleJiveSigningKeysError = 'MultipleJiveSigningKeysError',
+  MultipleJiveAuthnKeysError = 'MultipleJiveAuthnKeysError',
+  MissingCredentialIdError = 'MissingCredentialIdError',
+  SigningAuthnKeyMismatchError = 'SigningAuthnKeyMismatchError',
+  AgentStartFailedError = 'AgentStartFailedError',
+  AgentProcedureFailedError = 'AgentProcedureFailedError',
+  GitCloneFailedError = 'GitCloneFailedError',
+  GitConfigFailedError = 'GitConfigFailedError',
+}
+
+function* gitSetup(ownerRepoArg?: string): Effect.fn.Return<void, string, AllModules> {
+  const git = yield* cliModules.Git;
+  const github = yield* cliModules.GitHub;
+  const agentClient = yield* cliModules.AgentClient;
+  const sshConfig = yield* commonModules.SSHConfig;
+  const isCloneMode = ownerRepoArg !== undefined;
+
+  // 1. Parse owner/repo
+  const { owner, repo } = yield* git.resolveOwnerAndRepo(Option.fromNullishOr(ownerRepoArg));
+  log(`Setting up ${owner}/${repo}`);
+
+  // 2. GitHub OAuth
+  const token = yield* github.authorize(GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, OAUTH_SCOPES);
+  log('✓ Authorized with GitHub');
+
+  // 3. Fetch user info
+  const { login, email } = yield* github.getUser(token);
+  const gitUser: GitUser = {name: login, email: email};
+  log(`  Logged in as: ${gitUser.name} <${gitUser.email}>`);
+
+  // 4. Check GitHub signing keys for <tool name>: prefix
+  const signingKeys = yield* github.getSigningKeys(token);
+  const toolKeys = signingKeys.filter(k => k.title.startsWith(KEY_PREFIX));
+  if (toolKeys.length > 1)
+    return yield* Effect.fail(`${GitSetupError.MultipleJiveSigningKeysError}: Found ${toolKeys.length} signing keys with "${KEY_PREFIX}" prefix — expected at most 1`);
+  let maybeKey: Option.Option<{ credentialId: string; pubkey: string }> = Option.none();
+  if (toolKeys[0]) {
+    const credentialId = parseCredentialIdFromTitle(toolKeys[0].title);
+    if (Option.isNone(credentialId))
+      return yield* Effect.fail(`${GitSetupError.MissingCredentialIdError}: signing key title "${toolKeys[0].title}" has no credentialId`);
+    maybeKey = Option.some({ credentialId: credentialId.value, pubkey: baseKey(toolKeys[0].key) });
+  }
+
+  // 5. Check authn keys too — must match signing key if both present.
+  const authnKeys = yield* github.getAuthnKeys(token);
+  const toolAuthnKeys = authnKeys.filter(k => k.title.startsWith(KEY_PREFIX));
+  if (toolAuthnKeys.length > 1)
+    return yield* Effect.fail(`${GitSetupError.MultipleJiveAuthnKeysError}: Found ${toolAuthnKeys.length} authn keys with "${KEY_PREFIX}" prefix — expected at most 1`);
+  let maybeAuthnKey: Option.Option<{ credentialId: string; pubkey: string }> = Option.none();
+  if (toolAuthnKeys[0]) {
+    const credentialId = parseCredentialIdFromTitle(toolAuthnKeys[0].title);
+    if (Option.isNone(credentialId))
+      return yield* Effect.fail(`${GitSetupError.MissingCredentialIdError}: authn key title "${toolAuthnKeys[0].title}" has no credentialId`);
+    maybeAuthnKey = Option.some({ credentialId: credentialId.value, pubkey: baseKey(toolAuthnKeys[0].key) });
+  }
+  if (Option.isSome(maybeKey) && Option.isSome(maybeAuthnKey) && maybeKey.value.pubkey !== maybeAuthnKey.value.pubkey)
+    return yield* Effect.fail(`${GitSetupError.SigningAuthnKeyMismatchError}: signing key and authn key pubkeys don't match — GitHub account is in an inconsistent state`);
+
+  // 6. Call agent to get/create/verify key (starts agent if not running)
+  const { credentialId, pubkey } = yield* pipe(
+    Effect.gen(() => agentClient.usingClient(function* (client): EffectGen<{ pubkey: string; credentialId: string }, string> {
+      return yield* pipe(
+        client.Setup({
+          pubkey: Option.map(maybeKey, k => k.pubkey),
+          credentialId: Option.map(maybeKey, k => k.credentialId),
+          username: login,
+        }),
+        Effect.mapError(e => `${GitSetupError.AgentProcedureFailedError}: ${String(e)}`)
+      );
+    })),
+    Effect.catchTag("AgentClientError", err => Effect.fail(err.reason)),
+    Effect.catchTag("AgentClientUsageError", err => Effect.fail(err.cause))
+  );
+  const credentialFriendlyName = new CredentialId(credentialId).humanReadableName;
+  const keyTitle = `${credentialFriendlyName} (${credentialId})`;
+
+  // 8. Register signing key on GitHub if not already present
+  if (Option.isNone(maybeKey)) {
+    yield* github.addSigningKey(token, keyTitle, pubkey);
+    log(`✓ Registered GitHub signing key: ${keyTitle}`);
+  }
+
+  // 9. Register key as authn key on GitHub account if not already present
+  if (Option.isNone(maybeAuthnKey)) {
+    yield* github.addAuthnKey(token, keyTitle, pubkey);
+    log(`✓ Registered authn key on GitHub account`);
+  }
+
+  // 10. Write ssh config (pubkey file written by agent via KeyMapStore.addKey)
+  const pubkeyPath = sshConfig.getPubkeyPath(credentialFriendlyName);
+  yield* sshConfig.writeHost({
+    section: {
+      HostName: "github.com",
+      User: "git",
+      IdentityFile: pubkeyPath,
+      IdentitiesOnly: "yes",
+      IdentityAgent: AGENT_SOCK_FILE_PATH,
+    },
+  });
+
+  // 11. Clone if in clone mode
+  if (isCloneMode) {
+    yield* git.clone(owner, repo);
+    log(`✓ Cloned into ${repo}/`);
+  }
+
+  // 12. Set repo config plus any submodules' config
+  log('\nSetting git config:');
+  yield* git.setupRepo({
+    dir: process.cwd(),
+    remoteURL: `${STANDARD_REMOTE_PREFIX}${owner}/${repo}.git`,
+    user: gitUser,
+    pubkeyPath,
+  });
+
+  log(`\n✓ Setup complete for ${owner}/${repo}`);
+}
+
+const layerLive = pipe(
+  GitImpl.Layer,
+  Layer.provideMerge(GitHubImpl.Layer),
+  Layer.provideMerge(AgentClientImpl.Layer),
+  Layer.provideMerge(OSPlatformImpl.Layer),
+  Layer.provideMerge(SSHConfigImpl.Layer),
+  Layer.provideMerge(BunFileSystem.layer)
+)
+
+export const setup = new Command('setup')
+  .description('setup verified git commits for current repo')
+  .argument('[owner/repo]', 'GitHub repo to clone and set up (omit if already in a repo with a remote)')
+  .action(async (ownerRepo?: string) => {
+    function* program() {
+      yield* pipe(
+        effunct(gitSetup)(ownerRepo),
+        Effect.provide(layerLive),
+        Effect.catch(err => Effect.gen(function* () {
+          log(`✗ ${err}`);
+        }))
+      );
+    }
+    await Effect.runPromise(Effect.gen(program));
+    process.exit();
+  });

package/src/commands/index.ts

@@ -0,0 +1,15 @@
+import { program } from 'commander';
+import { git } from './git';
+import { npm } from './npm';
+import { upgrade } from './upgrade';
+import { ssh } from "./ssh";
+import { CLI_CMD_NAME, CURRENT_VERSION } from '@/common/constants';
+
+program.name(CLI_CMD_NAME).version(CURRENT_VERSION);
+
+[git, npm, ssh, upgrade]
+  .forEach(cmd => { program.addCommand(cmd) });
+
+program.parse();
+
+if (process.argv.length <= 2) program.help();

package/src/commands/npm/index.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+import { setup } from './setup';
+
+export const npm = new Command('npm')
+  .summary('npm package management utilities');
+
+[setup]
+  .forEach(cmd => { npm.addCommand(cmd) });

package/src/commands/npm/setup/git-remote.ts

@@ -0,0 +1,78 @@
+import { $ } from 'bun';
+import { Effect, Option } from 'effect';
+
+export interface RepoAccess {
+  owner: string;
+  repo: string;
+  canPush: boolean;
+}
+
+export interface CreatedRepo {
+  owner: string;
+  repo: string;
+  url: string;
+  sshUrl: string;
+}
+
+// Handles https://github.com/owner/repo.git, git@github.com:owner/repo.git,
+// and SSH aliases like github-ozyman42:owner/repo.git
+export function parseGithubOwnerRepo(url: string): Option.Option<{ owner: string; repo: string }> {
+  const https = url.match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (https) return Option.some({ owner: https[1]!, repo: https[2]! });
+  const alias = url.match(/^[^:]+:([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (alias) return Option.some({ owner: alias[1]!, repo: alias[2]! });
+  return Option.none();
+}
+
+async function viewRepo(nameWithOwner: string): Promise<Option.Option<CreatedRepo>> {
+  const view = await $`gh repo view ${nameWithOwner} --json name,owner,url,sshUrl`.quiet().nothrow();
+  if (view.exitCode !== 0) return Option.none();
+  try {
+    const data = JSON.parse(view.stdout.toString());
+    return Option.some({ owner: data.owner.login, repo: data.name, url: data.url, sshUrl: data.sshUrl });
+  } catch {
+    return Option.none();
+  }
+}
+
+export function ensureGitHubRepo(name: string, isPrivate = false): Effect.Effect<{ repo: CreatedRepo; created: boolean }, string> {
+  return Effect.tryPromise({
+    try: async () => {
+      const whoami = await $`gh api user --jq .login`.quiet().nothrow();
+      const owner = whoami.exitCode === 0 ? whoami.stdout.toString().trim() : null;
+
+      if (owner) {
+        const existingOption = await viewRepo(`${owner}/${name}`);
+        if (Option.isSome(existingOption)) return { repo: existingOption.value, created: false };
+      }
+
+      const visibility = isPrivate ? '--private' : '--public';
+      const create = await $`gh repo create ${name} ${visibility}`.quiet().nothrow();
+      if (create.exitCode !== 0) {
+        throw new Error(`gh repo create failed: ${create.stderr.toString().trim()}`);
+      }
+      const createdOption = await viewRepo(name);
+      if (Option.isNone(createdOption)) throw new Error(`repo created but could not retrieve details for "${name}"`);
+      return { repo: createdOption.value, created: true };
+    },
+    catch: (e) => e instanceof Error ? e.message : String(e),
+  });
+}
+
+export async function checkGitHubAccess(remoteUrl: string): Promise<Option.Option<RepoAccess>> {
+  const parsedOption = parseGithubOwnerRepo(remoteUrl);
+  if (Option.isNone(parsedOption)) return Option.none();
+  const { owner, repo } = parsedOption.value;
+
+  const result = await $`gh api repos/${owner}/${repo}`.quiet().nothrow();
+  if (result.exitCode !== 0) return Option.none();
+
+  let data: any;
+  try {
+    data = JSON.parse(result.stdout.toString());
+  } catch {
+    return Option.none();
+  }
+
+  return Option.some({ owner, repo, canPush: data?.permissions?.push === true });
+}