@telepath-computer/stash 0.2.3 → 0.3.1

package/README.md

@@ -11,15 +11,24 @@ npm install -g @telepath-computer/stash
 Set up GitHub access and connect the current directory:
 
 ```bash
-stash background install
-stash init
 stash setup github
-stash connect github --repo user/repo --background
+stash connect github --repo user/repo
+stash start
 ```
 
-You can initialize a directory explicitly with `stash init`, or let `stash connect` create `.stash/` for you automatically.
+You'll need a GitHub personal access token. We recommend a **fine-grained token** scoped to only the repos you use with stash.
 
-You'll need a GitHub [personal access token](https://github.com/settings/tokens). A classic token needs the `repo` scope. A fine-grained token needs **Contents: Read and write** permission on the target repo.
+### Creating a GitHub Token
+
+1. Go to [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
+2. Give it a name (e.g. `stash`)
+3. Under **Repository access**, select **Only select repositories** and pick the repo(s) you'll sync
+4. Under **Repository permissions**, set **Contents** to **Read and write**
+5. Click **Generate token** and copy it
+
+Use this token when running `stash setup github`.
+
+> A classic token with the `repo` scope also works, but grants broader access than necessary.
 
 ## How It Works
 
@@ -31,28 +40,37 @@ You'll need a GitHub [personal access token](https://github.com/settings/tokens)
 ## Commands
 
 ```bash
-stash background install
-stash background add
-stash init
 stash setup github
-stash connect github --repo user/repo --background
+stash connect github --repo user/repo
+stash start
+stash stop
 stash sync
 stash watch
-stash background status
 stash status
+stash status --all
+stash disconnect
 stash disconnect github
-stash background remove
-stash background uninstall
 ```
 
 `stash watch` keeps the directory in sync continuously. Press `.` to trigger an immediate sync and `q` to quit.
 
-`stash background install` plus `stash connect --background` gives you boot-time background syncing managed by `launchd` on macOS or `systemd` on Linux.
+`stash start` enables boot-time background syncing managed by `launchd` on macOS or `systemd` on Linux. Connected stashes are registered automatically.
+
+`stash disconnect` removes the current stash completely. `stash disconnect <provider>` removes one provider connection and removes `.stash/` too if that was the last one.
+
+Typical `stash start` output:
+
+```text
+Background sync is on
+Watching 1 stash · starts on startup
+```
 
 ## Config
 
 - Global config lives at `~/.stash/config.json` or `$XDG_CONFIG_HOME/stash/config.json`.
-- Per-stash connection config lives at `.stash/config.local.json` inside the synced directory.
+- Per-stash config lives at `.stash/config.json` inside the synced directory.
+
+Older prerelease stashes using `.stash/config.local.json` and `.stash/snapshot.local/` are migrated automatically on startup.
 
 Example global config:
 
@@ -71,6 +89,7 @@ Example global config:
 
 - `docs/api.md` - developer-facing `Stash` and provider contracts
 - `docs/architecture.md` - core components and repo boundaries
+- `docs/config.md` - config locations, metadata files, and config key conventions
 - `docs/sync.md` - sync lifecycle, locking, drift, and snapshot semantics
 - `docs/reconciliation.md` - merge and file-resolution rules
 - `docs/cli.md` - user-facing CLI behavior
@@ -87,6 +106,12 @@ Not blindly. On first sync, local and remote content are reconciled rather than
 
 Yes, but not on the same machine and directory. Stash syncs the working tree directly to `main` through the GitHub API and does not understand local git state.
 
+## Using Stash With Git
+
+By default, stash refuses to sync a directory that contains `.git/`. Branch switches look like mass file edits to stash, so syncing inside a git working tree can push destructive changes to the remote.
+
+If you do not need git in that directory, remove `.git/`. If you intentionally want both, run `stash config set allow-git true` first, then keep stash pinned to one branch and do not switch branches while stash is active.
+
 **Does stash use branches or PRs?**
 
 No. Stash reads and writes the `main` branch directly.

package/dist/cli-main.d.ts

@@ -7,6 +7,10 @@ type ServiceHandle = {
         running: boolean;
     }>;
 };
+type ServiceLaunch = {
+    command: string;
+    args: string[];
+};
 type CliDependencies = {
     cwd?: () => string;
     readGlobalConfig?: () => Promise<GlobalConfig>;
@@ -16,7 +20,7 @@ type CliDependencies = {
     stdout?: NodeJS.WriteStream;
     stderr?: NodeJS.WriteStream;
 };
-export declare function resolveStashCommand(): Promise<string>;
+export declare function resolveServiceLaunch(argv?: string[]): Promise<ServiceLaunch>;
 export declare function main(argv?: string[], deps?: CliDependencies): Promise<void>;
 export {};
 //# sourceMappingURL=cli-main.d.ts.map

package/dist/cli-main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-main.d.ts","sourceRoot":"","sources":["../src/cli-main.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAS,YAAY,EAAiB,MAAM,YAAY,CAAC;AAKrE,KAAK,aAAa,GAAG;IACnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC7D,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;CAC7B,CAAC;AAkCF,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAoB3D;AAoXD,wBAAsB,IAAI,CAAC,IAAI,WAAe,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+IzF"}
+{"version":3,"file":"cli-main.d.ts","sourceRoot":"","sources":["../src/cli-main.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAS,YAAY,EAAiB,MAAM,YAAY,CAAC;AAKrE,KAAK,aAAa,GAAG;IACnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC7D,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;CAC7B,CAAC;AAgEF,wBAAsB,oBAAoB,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAuBtF;AAmgBD,wBAAsB,IAAI,CAAC,IAAI,WAAe,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8JzF"}