@edspencer/paddock 0.59.1 → 0.61.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed Spencer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,8 @@ npx @edspencer/paddock
 
 Then open <http://127.0.0.1:4000>.
 
+Or point it at work you've already done — see [Open your own project](#open-your-own-project).
+
 > **First run downloads ~250 MB.** Paddock drives Claude Code, and the Claude
 > Agent SDK ships a per-platform binary of that size. It cannot be skipped —
 > installing with `--omit=optional` produces a Paddock whose chats all fail.
@@ -27,17 +29,45 @@ export ANTHROPIC_API_KEY=sk-ant-…   # or API billing
 If you already use Claude Code on this machine, your existing login is picked up
 automatically and there is nothing to do.
 
+## Open your own project
+
+```sh
+cd ~/code/some-project        # somewhere you've used Claude Code
+npx @edspencer/paddock --here
+```
+
+`--here` opens **that directory** as Paddock's workspace: Claude works in your files,
+and any Claude Code sessions you already have for the directory are offered for
+import. It's the fastest way to see what Paddock does with real history instead of an
+empty instance. Later runs in the same directory resume it — no flag needed.
+
+The flag is the consent, so here is everything it does:
+
+- creates **`.paddock/`** for the workspace's state and **`.chats/`** for transcripts
+- appends those two entries to **`.gitignore`**
+- **links** `~/.claude/projects/<encoded-dir>` at the workspace — your Claude Code
+  history is linked, never moved or copied
+
+To undo it: `rm -rf .paddock .chats` and drop the two `.gitignore` lines.
+
+Without `--here`, Paddock never touches the directory you ran it from.
+
 ## Options
 
 ```
   -p, --port <port>       HTTP/WS port (default 4000)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock)
+      --here              Open the CURRENT directory as the workspace
+  -o, --open              Open the app in your browser once it is listening
+      --verbose           Show the server's own logs (quiet by default)
   -v, --version           Print the version
   -h, --help              Show help
 ```
 
-Your projects, chats and settings live in `~/.paddock` and persist between runs.
+Your projects, chats and settings persist between runs in `~/.paddock` — or in
+`<dir>/.paddock` when you use `--here`. Either way it's one directory: move it to
+move your instance, delete it to start over.
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.59.1",
+  "version": "0.61.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -37,7 +37,7 @@
     "@fastify/swagger-ui": "4.2.0",
     "@fastify/websocket": "10.0.1",
     "@herdctl/chat": "0.8.0",
-    "@herdctl/core": "5.29.1",
+    "@herdctl/core": "5.31.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "fastify": "4.28.1",
     "jose": "6.2.3",
@@ -53,7 +53,8 @@
     "packages/server/package.json",
     "packages/web/dist",
     "install-notice.mjs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public",

package/packages/server/dist/adoptable.d.ts

@@ -1,11 +1,52 @@
 import { type AdoptableSession } from "@herdctl/core";
 import type { Project } from "./projects.js";
+/**
+ * One session on offer, with enough about it to decide (#660).
+ *
+ * The import used to be a single unconfirmed click, so an id was all the count
+ * needed. A confirmation dialog has to show the user WHAT it is about to import —
+ * and on the instance that prompted this, three quarters of the offer was things
+ * the user would have declined on sight. Every field here is already computed by
+ * the engine's scan; none of it costs an extra transcript parse.
+ */
+export interface AdoptableCandidate {
+    sessionId: string;
+    /** ISO 8601 last-modified time of the transcript (also the sort order). */
+    mtime: string;
+    /** First user message, truncated by the engine at 100 chars. */
+    preview?: string;
+    /** Auto-generated session name, when the transcript carries a summary. */
+    autoName?: string;
+    sizeBytes: number;
+}
 /** One working directory that has adoptable sessions, and which ones. */
 export interface AdoptableSource {
-    /** The working directory whose transcript folder holds these sessions. */
+    /**
+     * The working directory whose transcript folder holds these sessions — the
+     * DISPLAY identity, and the value a client round-trips back to import one
+     * source. Always a directory the user would recognise.
+     */
     sourceCwd: string;
-    /** Adoptable session ids, newest transcript first. */
+    /**
+     * The path the ENGINE must be handed to read this source, when that differs
+     * from {@link sourceCwd} (#620).
+     *
+     * It differs for the user's own `~/.claude` history, which paddock reaches
+     * through a mirror named for a synthetic path — see
+     * `mirrorLegacyTranscriptFolders`. Server-internal: absent means "same as
+     * sourceCwd", and clients neither send it nor need to know it exists.
+     */
+    importFrom?: string;
+    /**
+     * Adoptable session ids, newest transcript first.
+     *
+     * Exactly the ids of {@link sessions}, both built from one array at one site
+     * below so they cannot drift. Kept because it is the documented response shape
+     * and the narrower thing most callers want.
+     */
     sessionIds: string[];
+    /** The same sessions, with what a confirmation dialog needs to describe them. */
+    sessions: AdoptableCandidate[];
 }
 /** A candidate that detection deliberately did NOT offer, and why. */
 export interface FilteredSession {
@@ -14,11 +55,11 @@ export interface FilteredSession {
     reason: FilterReason;
 }
 /**
- * Why a candidate was withheld. Both values are OURS (paddock-side noise
+ * Why a candidate was withheld. All three values are OURS (paddock-side noise
  * filtering); the engine's own exclusions (sidechain / already-adopted /
  * attributed-to-run) never reach us as candidates at all.
  */
-export type FilterReason = "too-small" | "slash-command-only";
+export type FilterReason = "too-small" | "slash-command-only" | "sweeper-run";
 /** What a project could import right now. */
 export interface AdoptableSummary {
     /** Total adoptable sessions across every source, after de-dup and filtering. */
@@ -55,6 +96,33 @@ export declare const MIN_TRANSCRIPT_BYTES = 256;
  * more than a command plus its output, comfortably less than a conversation.
  */
 export declare const SLASH_COMMAND_MAX_BYTES = 4096;
+/**
+ * Does this transcript preview look like paddock's own sweeper run (#658)?
+ *
+ * Exported so `sweeper-prompt-contract.test.ts` can assert it against the prompt
+ * `SweepService` REALLY builds. The wording has drifted once already; a copy of
+ * it pasted into a test here would go stale silently and take the filter with it.
+ */
+export declare function isSweeperPrompt(preview: string): boolean;
+/**
+ * Reduce a git remote URL to a comparable `host/path` identity (#659).
+ *
+ * The same repo is written many ways, and a project's `repo` field and a clone's
+ * configured remote routinely disagree on form while naming the same thing:
+ *
+ *   https://github.com/edspencer/hushpod.git   ┐
+ *   git@github.com:edspencer/hushpod           ├─ all → github.com/edspencer/hushpod
+ *   ssh://git@github.com/edspencer/hushpod/    ┘
+ *
+ * So: drop any scheme, drop `user@`, turn the scp-style `host:path` colon into a
+ * slash, drop a trailing `.git` and any trailing slashes, and lowercase. A local
+ * path remote (`/srv/git/foo.git`) normalises to `/srv/git/foo` and still
+ * compares correctly against itself.
+ *
+ * Returns `""` for anything that reduces to nothing, which never compares equal
+ * to a real remote — the caller does not have to special-case it.
+ */
+export declare function normalizeRemote(url: string): string;
 /** The engine surface this module needs — narrowed so tests can fake it. */
 export interface AdoptableFleet {
     listAdoptableSessions(agentName: string, fromWorkingDir?: string): Promise<AdoptableSession[]>;
@@ -88,11 +156,38 @@ export interface AdoptableFleet {
 export declare class AdoptableIndex {
     private readonly claudeHomePath;
     private readonly stateDir;
+    /**
+     * The user's own `~/.claude` (#620). Now that paddock owns its Claude home,
+     * the user's CLI history — the entire point of adoption — is no longer under
+     * `claudeHomePath`, and the engine resolves every adoption path against the
+     * one home the FleetManager was built with, with no per-call override.
+     * {@link scanFolders} therefore mirrors the legacy folders in first,
+     * read-only. Defaults to `claudeHomePath` (i.e. no mirroring at all) for
+     * callers still running in the user's own home.
+     */
+    private readonly legacyClaudeHomePath;
     /** folder name → last-seen entry, reused while its `key` is unchanged. */
     private readonly folders;
+    /**
+     * checkout dir → its normalised remotes, memoised on the git config's own
+     * mtime+size (#659). Keyed on the config rather than the transcript folder
+     * because that is the file whose CHANGE would change the answer: adding or
+     * re-pointing a remote must be picked up, and it does not touch `~/.claude`.
+     */
+    private readonly remotes;
     /** project key → cached summary + the composite key it was computed under. */
     private readonly summaries;
-    constructor(claudeHomePath: string, stateDir: string);
+    constructor(claudeHomePath: string, stateDir: string, 
+    /**
+     * The user's own `~/.claude` (#620). Now that paddock owns its Claude home,
+     * the user's CLI history — the entire point of adoption — is no longer under
+     * `claudeHomePath`, and the engine resolves every adoption path against the
+     * one home the FleetManager was built with, with no per-call override.
+     * {@link scanFolders} therefore mirrors the legacy folders in first,
+     * read-only. Defaults to `claudeHomePath` (i.e. no mirroring at all) for
+     * callers still running in the user's own home.
+     */
+    legacyClaudeHomePath?: string);
     /**
      * Drop a project's cached summary (or every project's, with no argument).
      * Called after an import, which changes the adoptable set in a way the caller
@@ -108,6 +203,14 @@ export declare class AdoptableIndex {
      * folders whose file set changed since last time.
      */
     private scanFolders;
+    /**
+     * A checkout's normalised git remotes, memoised on its config's mtime+size.
+     *
+     * The memo is keyed by directory and re-validated on every call, so a remote
+     * added or re-pointed after the last scan is picked up without waiting for
+     * anything in `~/.claude` to change.
+     */
+    private remotesFor;
     /**
      * The candidate source working directories for a project, de-duplicated by the
      * transcript folder they resolve to.