dsh-plugin-standalone-session 0.0.0-stage → 0.1.0

package/lib/types/shared/standalone.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Pure, platform-neutral rules shared by the host half, the browser half and
+ * the tests. Nothing here touches `node:fs`, the DSH runtime or the DOM.
+ *
+ * The durable standalone marker is the session's own working directory: the
+ * host and the browser both mint and recognize
+ * `<DSH_HOME>/dsh-standalone-sessions/<sessionId>`. A host-owned JSON registry
+ * records richer lifecycle facts (first user message, cleanup state), but the
+ * browser never depends on reading that file: the session's durable `cwd`
+ * already carries the marker across restarts.
+ */
+/** Directory under the DSH home that owns every standalone session cwd. */
+export declare const STANDALONE_DIR_NAME = "dsh-standalone-sessions";
+/** Prefix for every session identity this plugin mints. */
+export declare const SESSION_ID_PREFIX = "session-";
+/** Schema version of the host-owned registry file. */
+export declare const REGISTRY_VERSION: 1;
+/** Name of the host-owned registry file inside the standalone root. */
+export declare const REGISTRY_FILE_NAME = "registry.json";
+/** One durable standalone-session record. */
+export interface StandaloneEntry {
+    readonly sessionId: string;
+    readonly cwd: string;
+    /** Durable marker; never inferred from a missing workspace id. */
+    readonly standalone: true;
+    readonly createdAt: number;
+    /** Whether a user-authored durable message was ever observed. */
+    readonly hadMessage: boolean;
+    /** Set once the session is archived (the native delete gesture). */
+    readonly archived?: boolean;
+    /** Set when the host could not remove the session directory. */
+    readonly cleanupFailed?: boolean;
+    readonly cleanupError?: string;
+    readonly cleanedAt?: number;
+}
+/** The complete registry payload written to disk. */
+export interface StandaloneRegistryData {
+    readonly version: typeof REGISTRY_VERSION;
+    readonly sessions: Readonly<Record<string, StandaloneEntry>>;
+}
+/** A cleanup decision derived from a record and the directory's live state. */
+export type CleanupPlan = {
+    readonly action: 'remove-entry';
+    readonly reason: 'missing';
+} | {
+    readonly action: 'remove-tree';
+    readonly reason: 'never-used';
+} | {
+    readonly action: 'keep';
+    readonly reason: 'used' | 'not-empty';
+};
+/** Injectable random UUID source used by tests. */
+export type UuidSource = () => string;
+/** An empty registry payload. */
+export declare function emptyRegistry(): StandaloneRegistryData;
+/**
+ * Whether a session cwd carries this plugin's standalone marker segment with a
+ * session child below it. The comparison is case-insensitive so a shared home
+ * path mounted with different casing still classifies correctly.
+ * @param cwd - session working directory, if any.
+ * @returns whether the cwd lives below a `dsh-standalone-sessions` directory.
+ */
+export declare function isStandaloneCwd(cwd: string | undefined | null): boolean;
+/**
+ * The final path segment of a standalone cwd, when the cwd is one.
+ * @param cwd - session working directory.
+ * @returns the segment below the standalone root, or undefined.
+ */
+export declare function standaloneSessionIdFromCwd(cwd: string | undefined | null): string | undefined;
+/**
+ * Join path segments with the separator family the base path already uses.
+ * Kept browser-safe: no `node:path` import.
+ * @param base - absolute base path.
+ * @param segments - child names; traversal segments are rejected.
+ * @returns the joined path.
+ */
+export declare function joinPath(base: string, ...segments: string[]): string;
+/**
+ * Default root for standalone session directories under an OS home.
+ * @param home - host user home directory.
+ * @returns `<home>/.dsh/dsh-standalone-sessions`.
+ */
+export declare function defaultStandaloneRoot(home: string): string;
+/**
+ * Mint one standalone session cwd.
+ * @param home - host user home directory.
+ * @param sessionId - the pre-minted session identity.
+ * @returns the session directory below the default standalone root.
+ */
+export declare function makeStandaloneCwd(home: string, sessionId: string): string;
+/**
+ * Reject ids that could escape the standalone root when used as a directory.
+ * @param sessionId - candidate identity.
+ * @returns the identity, typed as a plain string.
+ */
+export declare function assertSessionId(sessionId: unknown): string;
+/**
+ * One RFC 4122 version-4 UUID, with a non-cryptographic fallback for hosts
+ * without `crypto.randomUUID` (the identity is a directory name, not a secret).
+ * @returns a lowercase UUID string.
+ */
+export declare function randomUuid(): string;
+/**
+ * Mint a DSH-shaped session identity.
+ * @param uuidSource - UUID source, injectable for deterministic tests.
+ * @returns `session-<uuid>`.
+ */
+export declare function mintSessionId(uuidSource?: UuidSource): string;
+/**
+ * Validate and normalize an unknown on-disk registry payload. Malformed entries
+ * are dropped rather than repaired into a wrong directory.
+ * @param value - parsed JSON value.
+ * @returns a complete registry payload.
+ */
+export declare function normalizeRegistry(value: unknown): StandaloneRegistryData;
+/**
+ * Insert or refresh one session record. An existing record keeps the original
+ * creation time and its first-message fact; the cwd always follows the observed
+ * session header so a moved home cannot leave a stale cleanup target.
+ * @param data - current registry.
+ * @param entry - observed standalone session.
+ * @returns the next registry (a new object).
+ */
+export declare function upsertEntry(data: StandaloneRegistryData, entry: StandaloneEntry): StandaloneRegistryData;
+/**
+ * Mark one record as having observed a user-authored durable message.
+ * @param data - current registry.
+ * @param sessionId - session identity.
+ * @returns the next registry, or the same reference when nothing changed.
+ */
+export declare function markHadMessage(data: StandaloneRegistryData, sessionId: string): StandaloneRegistryData;
+/**
+ * Record an archive observation without losing the cleanup target.
+ * @param data - current registry.
+ * @param sessionId - session identity.
+ * @returns the next registry, or the same reference when nothing changed.
+ */
+export declare function markArchived(data: StandaloneRegistryData, sessionId: string): StandaloneRegistryData;
+/**
+ * Drop one record after its directory cleanup succeeded.
+ * @param data - current registry.
+ * @param sessionId - session identity.
+ * @returns the next registry, or the same reference when absent.
+ */
+export declare function removeEntry(data: StandaloneRegistryData, sessionId: string): StandaloneRegistryData;
+/**
+ * Record a failed cleanup so a later sweep can retry and operators can see why.
+ * @param data - current registry.
+ * @param sessionId - session identity.
+ * @param message - diagnostic text.
+ * @returns the next registry.
+ */
+export declare function markCleanupFailed(data: StandaloneRegistryData, sessionId: string, message: string): StandaloneRegistryData;
+/** All records in stable id order. */
+export declare function listEntries(data: StandaloneRegistryData): StandaloneEntry[];
+/**
+ * Decide what a deletion may remove. A session that never carried a user
+ * message owns its directory completely; one that did keeps its directory so
+ * an unarchive can still resume in the recorded cwd.
+ * @param entry - registry record.
+ * @param directoryState - live directory facts.
+ * @returns the cleanup plan.
+ */
+export declare function cleanupPlan(entry: StandaloneEntry, directoryState: {
+    readonly exists: boolean;
+    readonly empty: boolean;
+}): CleanupPlan;
+/**
+ * Whether a composer render should be unlocked for one standalone session.
+ * The native InputBar disables itself when a session has no workspace; this
+ * plugin's standalone sessions are exactly that state.
+ * @param sessionId - rendered session (undefined on the New Session page).
+ * @param cwd - that session's durable working directory.
+ * @param disabled - the native composer's inert flag.
+ * @returns whether the override applies.
+ */
+export declare function shouldUnlockComposer(sessionId: string | undefined, cwd: string | undefined, disabled: boolean): boolean;
+/**
+ * Stable, human-readable relative time for panel rows.
+ * @param timestamp - epoch milliseconds; non-finite values return an empty string.
+ * @param now - comparison instant.
+ * @returns a short relative label.
+ */
+export declare function relativeTime(timestamp: number, now?: number): string;

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Standalone Session",
+    "description": "Create and manage standalone DSH sessions that are not attached to any workspace."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "独立会话",
+    "description": "创建并管理不隶属于任何工作区的独立 DSH 会话。"
+  }
+}

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "dsh-plugin-standalone-session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "displayName": "Standalone Session",
+  "description": "Create and manage standalone DSH sessions that are not attached to any workspace.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "locale",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "icon": "./icon.svg",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-commands",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run build && npm run test",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis-plugin",
+    "standalone-session",
+    "no-workspace"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/react": "^18.3.18",
+    "esbuild": "^0.28.2",
+    "react": "^18.3.1",
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LRainner/dsh-plugin-standalone-session.git"
+  },
+  "homepage": "https://github.com/LRainner/dsh-plugin-standalone-session#readme",
+  "bugs": {
+    "url": "https://github.com/LRainner/dsh-plugin-standalone-session/issues"
+  }
+}