@ankhorage/repository 0.4.0

package/dist/providers/github/services/inspectGitHubRepositoryPreflightAsync.js

@@ -0,0 +1,72 @@
+import { basename, resolve } from 'node:path';
+/** Inspect all local and remote state before allowing a repository mutation. */
+export async function inspectGitHubRepositoryPreflightAsync(options, gateway, snapshotReader, manifestStore) {
+    const projectPath = options.projectPath ?? process.cwd();
+    await gateway.assertAvailableAsync();
+    await gateway.assertAuthenticatedAsync();
+    const manifest = await manifestStore.readConfigAsync(projectPath);
+    const owner = options.owner ?? (await gateway.getAuthenticatedOwnerAsync());
+    const name = options.name ?? manifest?.name ?? getDefaultRepositoryName(projectPath);
+    validateName(owner, name);
+    const visibility = options.visibility ?? 'private';
+    const identity = {
+        owner,
+        name,
+        url: `https://github.com/${owner}/${name}`,
+        defaultBranch: 'main',
+    };
+    if (manifest && !matchesIdentity(manifest, identity)) {
+        throw new PreflightError('conflict', 'repository-mismatch', 'Local repository manifest does not match the requested target.');
+    }
+    const prospectiveManifest = { provider: 'github', ...identity };
+    const snapshot = await snapshotReader.readAsync(projectPath, prospectiveManifest);
+    const target = { ...identity, visibility };
+    const remote = await gateway.inspectRepositoryAsync(target);
+    validateRemoteState(remote, manifest, identity, visibility);
+    return { target, identity, manifest, snapshot, remote };
+}
+export class PreflightError extends Error {
+    kind;
+    code;
+    constructor(kind, code, message) {
+        super(message);
+        this.name = 'PreflightError';
+        this.kind = kind;
+        this.code = code;
+    }
+}
+/** Validate GitHub owner and repository names without invoking the provider. */
+function validateName(owner, name) {
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,98}[A-Za-z0-9])?$/u.test(owner)) {
+        throw new PreflightError('conflict', 'invalid-owner', 'GitHub owner is invalid.');
+    }
+    if (!/^[A-Za-z0-9._-]{1,100}$/u.test(name) || name === '.' || name === '..') {
+        throw new PreflightError('conflict', 'invalid-name', 'GitHub repository name is invalid.');
+    }
+}
+/** Compare only the canonical identity fields persisted in the repository manifest. */
+function matchesIdentity(repository, identity) {
+    return (repository?.provider === 'github' &&
+        repository.owner === identity.owner &&
+        repository.name === identity.name &&
+        repository.url === identity.url);
+}
+/** Reject remote state that cannot be safely resumed or connected. */
+function validateRemoteState(remote, manifest, identity, visibility) {
+    if (remote.exists && !manifest) {
+        throw new PreflightError('conflict', 'local-manifest-missing', 'An existing repository cannot be adopted without a matching local manifest.');
+    }
+    if (remote.exists && remote.visibility !== undefined && remote.visibility !== visibility) {
+        throw new PreflightError('conflict', 'visibility-mismatch', 'The existing repository has different visibility.');
+    }
+    if (remote.exists && remote.mainManifest !== undefined) {
+        if (!matchesIdentity(remote.mainManifest, identity)) {
+            throw new PreflightError('conflict', 'remote-manifest-mismatch', 'The remote repository manifest points to another repository.');
+        }
+    }
+}
+/** Derive a stable repository name for projects without a repository manifest. */
+function getDefaultRepositoryName(projectPath) {
+    return basename(resolve(projectPath));
+}
+//# sourceMappingURL=inspectGitHubRepositoryPreflightAsync.js.map

package/dist/providers/github/services/inspectGitHubRepositoryPreflightAsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspectGitHubRepositoryPreflightAsync.js","sourceRoot":"","sources":["../../../../src/providers/github/services/inspectGitHubRepositoryPreflightAsync.ts"],"names":[],"mappings":"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"}

package/dist/providers/github/services/publishGitHubProjectSnapshotAsync.d.ts

@@ -0,0 +1,8 @@
+import type { ProjectSnapshot } from '../../../connection/definitions/ProjectSnapshot.js';
+import type { GitHubRepositoryGateway, GitHubRepositoryTarget } from '../ports/GitHubRepositoryGateway.js';
+export interface GitHubSnapshotPublication {
+    readonly commitSha: string;
+}
+/** Publish a complete snapshot through bootstrap, one app commit, and verified cleanup. */
+export declare function publishGitHubProjectSnapshotAsync(gateway: GitHubRepositoryGateway, target: GitHubRepositoryTarget, snapshot: ProjectSnapshot, existingBootstrapCommitSha?: string): Promise<GitHubSnapshotPublication>;
+//# sourceMappingURL=publishGitHubProjectSnapshotAsync.d.ts.map

package/dist/providers/github/services/publishGitHubProjectSnapshotAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishGitHubProjectSnapshotAsync.d.ts","sourceRoot":"","sources":["../../../../src/providers/github/services/publishGitHubProjectSnapshotAsync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oDAAoD,CAAC;AAC1F,OAAO,KAAK,EAEV,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,qCAAqC,CAAC;AAE7C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,2FAA2F;AAC3F,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,uBAAuB,EAChC,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,eAAe,EACzB,0BAA0B,CAAC,EAAE,MAAM,GAClC,OAAO,CAAC,yBAAyB,CAAC,CASpC"}

package/dist/providers/github/services/publishGitHubProjectSnapshotAsync.js

@@ -0,0 +1,12 @@
+/** Publish a complete snapshot through bootstrap, one app commit, and verified cleanup. */
+export async function publishGitHubProjectSnapshotAsync(gateway, target, snapshot, existingBootstrapCommitSha) {
+    const bootstrap = existingBootstrapCommitSha
+        ? { branch: 'ankh-bootstrap', commitSha: existingBootstrapCommitSha }
+        : await gateway.initializeBootstrapAsync(target);
+    const published = await gateway.publishSnapshotAsync(target, snapshot, bootstrap.commitSha);
+    await gateway.verifyPublishedSnapshotAsync(target, snapshot, published.commitSha);
+    await gateway.setDefaultBranchAsync(target);
+    await gateway.deleteBootstrapAsync(target, bootstrap);
+    return { commitSha: published.commitSha };
+}
+//# sourceMappingURL=publishGitHubProjectSnapshotAsync.js.map

package/dist/providers/github/services/publishGitHubProjectSnapshotAsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishGitHubProjectSnapshotAsync.js","sourceRoot":"","sources":["../../../../src/providers/github/services/publishGitHubProjectSnapshotAsync.ts"],"names":[],"mappings":"AAWA,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,OAAgC,EAChC,MAA8B,EAC9B,QAAyB,EACzB,0BAAmC;IAEnC,MAAM,SAAS,GAAoB,0BAA0B;QAC3D,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,0BAA0B,EAAE;QACrE,CAAC,CAAC,MAAM,OAAO,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC5F,MAAM,OAAO,CAAC,4BAA4B,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAClF,MAAM,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,OAAO,CAAC,oBAAoB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtD,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;AAC5C,CAAC"}

package/dist/readme-usage.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=readme-usage.d.ts.map

package/dist/readme-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme-usage.d.ts","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":""}

package/dist/readme-usage.js

@@ -0,0 +1,32 @@
+/***
+ * Connect a project folder to its source repository
+ *
+ * `@ankhorage/repository` consumes only the project's `RepositoryManifest` slice and delegates
+ * GitHub operations to the local authenticated `gh` adapter. It creates a missing repository,
+ * publishes the project snapshot to `main`, stores only the repository slice in
+ * `.ankhorage/repository.json`, and refuses unrelated existing repositories.
+ *
+ * See [`examples/basic-usage.ts`](../examples/basic-usage.ts) for a complete programmatic example.
+ *
+ * @usage
+ */
+import { connectRepositoryAsync } from '@ankhorage/repository';
+const result = await connectRepositoryAsync({
+    projectPath: './my-project',
+    repository: {
+        provider: 'github',
+        owner: 'ankhorage',
+        name: 'my-project',
+        url: 'https://github.com/ankhorage/my-project',
+        defaultBranch: 'main',
+    },
+    visibility: 'private',
+});
+if (result.status === 'conflict' || result.status === 'recoverable-failure') {
+    console.error(`${result.status}: ${result.message}`);
+    process.exitCode = 1;
+}
+else {
+    console.log(JSON.stringify(result));
+}
+//# sourceMappingURL=readme-usage.js.map

package/dist/readme-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme-usage.js","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC;IAC1C,WAAW,EAAE,cAAc;IAC3B,UAAU,EAAE;QACV,QAAQ,EAAE,QAAQ;QAClB,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,yCAAyC;QAC9C,aAAa,EAAE,MAAM;KACtB;IACD,UAAU,EAAE,SAAS;CACtB,CAAC,CAAC;AAEH,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,IAAI,MAAM,CAAC,MAAM,KAAK,qBAAqB,EAAE,CAAC;IAC5E,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@ankhorage/repository",
+  "version": "0.4.0",
+  "description": "Standalone repository capability for connecting and managing an app project's source repository.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "homepage": "https://github.com/ankhorage/repository#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/repository/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/repository.git"
+  },
+  "keywords": [
+    "ankhorage",
+    "repository",
+    "github",
+    "git",
+    "cli",
+    "automation",
+    "typescript",
+    "bun"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "default": "./dist/github/index.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata/index.d.ts",
+      "default": "./dist/metadata/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "ankh": {
+    "category": "repository",
+    "provider": "./dist/cli/index.js",
+    "capabilities": [
+      "repository.connect"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && bun x tsc -p tsconfig.json",
+    "changeset": "ankhorage-changeset",
+    "changeset:status": "ankhorage-changeset status --since=origin/main",
+    "docs": "paradox",
+    "test": "bun test src",
+    "typecheck": "bun x tsc --noEmit -p tsconfig.json",
+    "version-packages": "ankhorage-changeset version",
+    "lint": "ankhorage-eslint . --max-warnings=0",
+    "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
+    "format": "ankhorage-prettier --write .",
+    "format:check": "ankhorage-prettier --check .",
+    "knip:check": "ankhorage-knip"
+  },
+  "devDependencies": {
+    "@ankhorage/devtools": "^1.10.10",
+    "@ankhorage/paradox": "^0.1.24",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^24.13.3",
+    "typescript": "~6.0.3"
+  },
+  "packageManager": "bun@1.4.0",
+  "dependencies": {
+    "@ankhorage/contracts": "^10.0.0",
+    "ignore": "^7.0.8"
+  }
+}