halfcycle 0.4.0 → 0.4.2

package/dist/identity.d.ts

@@ -32,17 +32,17 @@
  * this id is *not*, and where the right one lives; it cannot answer the question
  * directly.
  *
- * **REWORDING THIS STRING REWRITES A FILE IN EVERY INSTALLED TREE AT ONCE, and
- * that is not what it looks like.** The identity writer reads `projectId`,
- * `rootCommit` and `remote` back off disk when the file is already there, so those
- * three survive a re-install — but it takes THIS field from this constant on every
- * run, never from disk. So a re-install after any edit here finds a file whose
- * bytes differ, replaces it, and reports a write; the developer's identity is
- * preserved and the file is not. The change reads like copy-editing and lands
- * everywhere the installer has ever run. If you must change it, change it knowing
- * that, and say so in the commit.
+ * **REWORDING THIS STRING SPLITS INSTALLED TREES IN TWO, and that is not what it
+ * looks like.** It is written into every NEW `project.json`, and an existing file is
+ * never rewritten (`writeProjectIdentity`; onboarding fix wave T-05). So after an
+ * edit here every tree set up earlier keeps the old text for good and every later
+ * one carries the new, with nothing on disk saying which is current. The change
+ * reads like copy-editing. If you must change it, change it knowing that, and say so
+ * in the commit.
  */
 export declare const PROJECT_IDENTITY_NOTE: string;
+/** Where the committed identity lives, relative to the folder being installed into. */
+export declare const PROJECT_IDENTITY_REL = ".halfcycle/project.json";
 /** The committed project identity: minted id plus the repo's root fingerprint. */
 export interface ProjectIdentity {
     /** A minted, stable project id (uuid). Assigned once, at first install. */
@@ -58,10 +58,9 @@ export interface ProjectIdentity {
     /**
      * A fixed disambiguation string, always `PROJECT_IDENTITY_NOTE` — see there.
      * Present so a session reading this file directly (not through a tool
-     * description) sees the warning too. Reconciled on every install: if an
-     * install written before this field existed re-installs, the note is
-     * backfilled (`writeProjectIdentity` rewrites iff the serialized bytes
-     * differ) — `projectId`/`rootCommit`/`remote` are never touched by that.
+     * description) sees the warning too. Written only when the file is created: a
+     * file from before this field existed keeps its bytes and never gains it
+     * (`writeProjectIdentity` never rewrites an existing `project.json`).
      */
     note: string;
 }
@@ -69,6 +68,19 @@ export interface ProjectIdentity {
 export declare function gitEnvForNamedRepo(): NodeJS.ProcessEnv;
 /** Read the repository's root commit hash (the first commit, reachable from HEAD). */
 export declare function readRootCommit(targetRepoRoot: string): string | null;
+/**
+ * Is `targetRepoRoot` inside a git working tree? Decides whether the install's
+ * closing output tells the person which files to commit (`project-identity-reuse`
+ * AC8) — outside a repository there is nothing to commit them to.
+ */
+export declare function isGitWorkTree(targetRepoRoot: string): boolean;
+/**
+ * Can this machine run `git` at all? Asked only once `isGitWorkTree` has said no,
+ * because `git()` above answers `null` for "not a repository" and for "no git" alike —
+ * and the advice differs: `git init` cannot help someone who has no Git (the macOS and
+ * Linux walks' B5, onboarding fix wave FW-1).
+ */
+export declare function gitIsInstalled(): boolean;
 /** Read the `origin` remote URL. */
 export declare function readRemote(targetRepoRoot: string): string | null;
 /**
@@ -132,4 +144,36 @@ export declare function mintOrReadIdentity(targetRepoRoot: string): {
     identity: ProjectIdentity;
     minted: boolean;
 };
+/**
+ * The ONE serializer for `project.json`, called from exactly one place:
+ * `createProjectIdentityFile` below, to produce the bytes for a freshly minted
+ * identity. `install()`'s `writeProjectIdentity` no longer calls this function
+ * itself — until the onboarding fix wave (T-05, from review R-03) it did, to
+ * reconcile an existing file's bytes against what it would have written and
+ * rewrite one that differed. That reconciliation is retired: `writeProjectIdentity`
+ * now only calls `createProjectIdentityFile`, which skips a file that is already
+ * there, whatever its bytes (`project-identity-reuse` AC1). A file the pre-write
+ * created is therefore read back as `skipped`, never compared or rewritten.
+ */
+export declare function serializeProjectIdentity(identity: ProjectIdentity): string;
+/**
+ * Create `.halfcycle/project.json` if it is absent, and never replace it
+ * (`project-identity-reuse` AC1, #1555 decision D1: the folder's id decides the
+ * project, so the id must exist before the installer asks for the project).
+ *
+ * A fresh identity is written to a temporary file beside the target and hard-linked
+ * into place. `linkSync` fails with `EEXIST` when the target is already there, which
+ * is the whole of the "never replace" rule: two installs started at the same moment
+ * both try, exactly one link lands, and both then read the one file that exists. A
+ * committed `project.json` from someone else is never rewritten. There is no
+ * "does it exist?" branch before the write, on purpose: the temporary write is also
+ * the check that this folder can be written to, so it runs on every call and a
+ * re-run in a folder that has since become read-only is refused before any request,
+ * not after a project was created. The temporary file is always removed.
+ *
+ * Throws whatever the filesystem throws for a folder it cannot write to; the caller
+ * (`pre-create-checks.ts`) turns that into a sentence. Reading and judging the file
+ * that ends up in place is the caller's too — this module imports only builtins.
+ */
+export declare function createProjectIdentityFile(targetRepoRoot: string): void;
 //# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,qBAAqB,QAGF,CAAC;AAEjC,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AA6BD,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,UAAU,CAItD;AAqBD,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMpE;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrE;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAyBvG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAmBzG"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,qBAAqB,QAGF,CAAC;AAEjC,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAE9D,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AA6BD,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,UAAU,CAItD;AAqBD,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAOxC;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrE;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAyBvG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAazG;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAiBtE"}