dsh-codespace-workspace 0.0.0-stage → 0.1.0

package/lib/shared.js

@@ -0,0 +1,181 @@
+/**
+ * Shared contract between the Host and Client halves of dsh-codespace-workspace.
+ *
+ * This module is imported by the Host bundle only. The Client bundle is a
+ * self-contained lazy-CJS factory and must repeat these literals; keep the two
+ * in sync — the values here are the wire contract.
+ *
+ * @module dsh-codespace-workspace/shared
+ */
+
+/** Package name; also the client module-loader id and the loader row id. */
+export const PLUGIN_ID = 'dsh-codespace-workspace'
+
+/** Exact host route the browser posts RPC calls to. */
+export const RPC_ROUTE = '/api/dsh-codespace-workspace/rpc'
+
+/**
+ * Directory under the DSH home that holds placeholder workspace folders.
+ * A Codespace workspace is registered in DSH's own workspace registry as a real
+ * local directory; `dsh-workspace` requires an existing, fully-qualified path.
+ * Relative to the harness home; the host resolves the absolute path.
+ */
+export const PLACEHOLDER_DIRNAME = 'codespaces'
+
+/** System-prompt section registered once, at session creation. */
+export const PROMPT_SECTION = 'codespace:workspace-rule'
+
+/**
+ * Prompt section order. After the deployment persona (0) and the plan/team
+ * policies (500/600), before the tool guidance (900+), so the rule is read as
+ * workspace context rather than as a tool instruction.
+ */
+export const PROMPT_ORDER = 1500
+
+/** The single rule injected for a Codespace session. */
+export const PROMPT_TEXT = [
+  'This session runs in a cloud Codespace workspace: file and command tools',
+  'operate inside a remote GitHub Codespace, not on the local machine.',
+  'When you finish a change, `git push` it back to the repository — the plugin',
+  'does not push for you and does not wrap Git in any way.',
+].join(' ')
+
+/** Every RPC action name. Frozen: the client repeats these strings. */
+export const ACTIONS = Object.freeze({
+  STATUS: 'status',
+  GET_SETTINGS: 'get-settings',
+  SET_SETTINGS: 'set-settings',
+  LIST_REPOS: 'list-repos',
+  LIST_CODESPACES: 'list-codespaces',
+  MACHINES: 'machines',
+  PREBUILD: 'prebuild',
+  CREATE: 'create',
+  START: 'start',
+  STOP: 'stop',
+  REMOVE: 'remove',
+  PAUSE_CANCEL: 'pause-cancel',
+  PAUSE_NOW: 'pause-now',
+  WORKSPACES: 'workspaces',
+  CREATE_WORKSPACE: 'create-workspace',
+  REMOVE_WORKSPACE: 'remove-workspace',
+})
+
+/**
+ * Codespace lifecycle state, normalized for the UI.
+ *
+ * The raw vocabulary is the `state` enum of the Codespaces REST API:
+ * `Unknown`, `Created`, `Queued`, `Provisioning`, `Available`, `Awaiting`,
+ * `Unavailable`, `Deleted`, `Moved`, `Shutdown`, `Archived`, `Starting`,
+ * `ShuttingDown`, `Failed`, `Exporting`, `Updating`, `Rebuilding`.
+ *
+ * @typedef {'running'|'stopped'|'pending'|'error'} CodespacePhase
+ */
+
+/** States that mean the Codespace is usable. */
+const RUNNING_STATES = new Set(['available'])
+
+/** States that mean it is not running and can be started. */
+const STOPPED_STATES = new Set(['shutdown', 'archived'])
+
+/**
+ * States that are transitional: show a spinner and disable the control.
+ * `awaiting` is included because it is a transient hand-off state, not a
+ * settled one — the API documents it as neither available nor stopped.
+ */
+const PENDING_STATES = new Set([
+  'created',
+  'queued',
+  'provisioning',
+  'starting',
+  'awaiting',
+  'shuttingdown',
+  'exporting',
+  'updating',
+  'rebuilding',
+])
+
+/** States that are terminal failures. */
+const ERROR_STATES = new Set(['failed', 'unavailable', 'deleted', 'moved', 'unknown'])
+
+/**
+ * Map a raw GitHub Codespaces state string onto a UI phase.
+ *
+ * Unknown and missing values are treated as `pending` rather than `error`: a
+ * state this build has never seen is far more likely to be a new transitional
+ * state than a broken Codespace, and `pending` disables the control instead of
+ * offering a start that would be rejected.
+ *
+ * @param {unknown} state - raw `state` field from the GitHub API.
+ * @returns {CodespacePhase} the normalized phase.
+ */
+export function codespacePhase(state) {
+  if (typeof state !== 'string') return 'pending'
+  // The enum is PascalCase (`ShuttingDown`); compare case-insensitively and
+  // tolerate a snake_case or spaced spelling from any other producer.
+  const key = state.trim().toLowerCase().replace(/[\s_-]+/g, '')
+  if (RUNNING_STATES.has(key)) return 'running'
+  if (STOPPED_STATES.has(key)) return 'stopped'
+  if (PENDING_STATES.has(key)) return 'pending'
+  if (ERROR_STATES.has(key)) return 'error'
+  return 'pending'
+}
+
+/** Whether a phase may be started. */
+export function canStart(phase) {
+  return phase === 'stopped' || phase === 'error'
+}
+
+/** Whether a phase may be stopped. */
+export function canStop(phase) {
+  return phase === 'running'
+}
+
+/** Settings namespace = the loader row id. */
+export const SETTINGS_NS = PLUGIN_ID
+
+/** Default settings values; also mirrored by the Host `Config` schema. */
+export const SETTINGS_DEFAULTS = Object.freeze({
+  githubUsername: '',
+  defaultBranch: 'main',
+  autoPauseMinutes: 30,
+  sshKeyPath: '',
+  alwaysShowCloudButton: false,
+  autoInitEmptyRepo: true,
+  readmeContent: '',
+})
+
+/**
+ * Reduce an unknown thrown value to a wire-safe `{ code, message }` pair.
+ * Never leaks a stack, a token, or a request body.
+ *
+ * @param {unknown} error - the caught value.
+ * @returns {{ code: string, message: string }} the wire error.
+ */
+export function wireError(error) {
+  if (error && typeof error === 'object') {
+    const code = typeof error.code === 'string' && error.code.length > 0 ? error.code : 'E_UNKNOWN'
+    const message = error instanceof Error ? error.message : String(error.message ?? error)
+    return { code, message: redact(message) }
+  }
+  return { code: 'E_UNKNOWN', message: redact(String(error)) }
+}
+
+/** Patterns that must never reach the browser. */
+const SECRET_PATTERNS = [
+  /\bgh[pousr]_[A-Za-z0-9]{16,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bBearer\s+[A-Za-z0-9._-]{20,}/gi,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+]
+
+/**
+ * Strip anything credential-shaped out of a string.
+ *
+ * @param {string} text - candidate text.
+ * @returns {string} the same text with credential-shaped runs replaced.
+ */
+export function redact(text) {
+  let out = text
+  for (const pattern of SECRET_PATTERNS) out = out.replace(pattern, '[redacted]')
+  return out
+}

package/locale/en.json

@@ -0,0 +1,122 @@
+{
+  "nav": "Codespace",
+  "page.title": "Codespace",
+  "page.subtitle": "Use a GitHub Codespace as a DSH workspace: file and command tools run inside the cloud Codespace.",
+  "status.heading": "Status",
+  "status.refresh": "Refresh",
+  "status.checking": "Checking…",
+  "status.gh": "GitHub CLI (gh)",
+  "status.gh.installed": "installed · {version}",
+  "status.gh.missing": "not installed",
+  "status.gh.missingNote": "The GitHub CLI was not found. That does not block the plugin: it connects to the Codespace through the SSH setting below instead (a host alias from ~/.ssh/config, such as codespace-mybox, is the recommended value). Installing gh enables the fuller capability set.",
+  "status.token": "GitHub token",
+  "status.token.settings": "from plugin settings",
+  "status.token.env": "from the GITHUB_TOKEN environment variable",
+  "status.token.gh": "from gh auth token",
+  "status.token.none": "not found",
+  "status.token.noneNote": "No token found: the repository list and the Codespace lifecycle actions are unavailable.",
+  "status.login": "GitHub login",
+  "status.loggedOut": "not signed in",
+  "status.configured": "Configuration",
+  "status.configured.yes": "configured",
+  "status.configured.no": "not configured",
+  "status.failed": "Could not read the status: {message}",
+  "settings.heading": "Settings",
+  "field.githubUsername": "GitHub username",
+  "field.githubUsername.hint": "Leave empty to use the account the token belongs to.",
+  "field.defaultBranch": "Default branch",
+  "field.autoPauseMinutes": "Auto-pause delay (minutes)",
+  "field.autoPauseMinutes.hint": "Counts down after a turn ends; a new message cancels it. 0 disables auto-pause. Double-click the clock on a workspace row to pause immediately.",
+  "field.sshKeyPath": "SSH key (optional)",
+  "field.sshKeyPath.hint": "Used to reach the Codespace when gh is unavailable. Put a host alias from ~/.ssh/config here (such as codespace-mybox); name the private key with IdentityFile in that Host entry — a key path alone does not say which host to reach.",
+  "field.sshKeyPath.set": "Set",
+  "field.sshKeyPath.unset": "Not set",
+  "field.sshKeyPath.write": "Enter a new value (never shown again)",
+  "field.sshKeyPath.save": "Save",
+  "field.sshKeyPath.clear": "Clear",
+  "field.alwaysShowCloudButton": "Always show the cloud workspace button",
+  "field.alwaysShowCloudButton.hint": "When off, the button appears only while the pointer is over that workspace row. When on, the row’s whole action cluster stays visible (CSS cannot reveal one child of a hidden container).",
+  "field.autoInitEmptyRepo": "Initialize empty repositories",
+  "field.autoInitEmptyRepo.hint": "Commit a README first when the repository has no commits.",
+  "field.readmeContent": "Initial README content",
+  "field.readmeContent.hint": "Leave empty to commit an empty README.md.",
+  "save": "Save",
+  "saving": "Saving…",
+  "saved": "Saved",
+  "saveFailed": "Save failed: {message}",
+  "managed.heading": "Cloud workspaces",
+  "managed.empty": "No Codespace workspace is managed by this plugin yet.",
+  "managed.loading": "Loading…",
+  "managed.new": "New cloud workspace",
+  "managed.delete": "Delete Codespace…",
+  "managed.deleteFallbackNote": "The workspace row’s “⋯” menu also offers “Delete Codespace…”. If it does not appear there, use the button here.",
+  "window.title": "New cloud workspace",
+  "step.repo": "Repository",
+  "step.codespace": "Codespace",
+  "step.machine": "Machine",
+  "step.apply": "Create",
+  "step.done": "Done",
+  "repo.search": "Search repositories",
+  "repo.loading": "Loading repositories…",
+  "repo.empty": "No repository matches.",
+  "repo.failed": "Could not load repositories: {message}",
+  "repo.private": "private",
+  "repo.isEmpty": "empty",
+  "repo.count": "{n} total",
+  "cs.heading": "This repository already has Codespaces",
+  "cs.pick": "Pick one",
+  "cs.none": "This repository has no Codespace yet; one will be created.",
+  "cs.loading": "Loading Codespaces…",
+  "cs.failed": "Could not load Codespaces: {message}",
+  "cs.state": "state: {state}",
+  "cs.createNew": "Create a new Codespace",
+  "prebuild.checking": "Checking for a prebuild…",
+  "prebuild.missing": "No prebuild configured — creating may be slow",
+  "prebuild.unknown": "Prebuild status could not be read — creating may take 1–3 minutes",
+  "prebuild.cancel": "Cancel",
+  "prebuild.proceed": "Create anyway",
+  "prebuild.ok": "This repository has a prebuild configured.",
+  "machine.heading": "Machine type",
+  "machine.loading": "Loading machine types…",
+  "machine.failed": "Could not load machine types: {message}",
+  "machine.empty": "No machine type is available for this repository.",
+  "machine.default": "smallest default",
+  "machine.cpus": "{n} CPUs",
+  "machine.memory": "{n} GB RAM",
+  "machine.storage": "{n} GB storage",
+  "machine.gpu": "GPU",
+  "seed.note": "The repository is empty: README.md is committed first, then the Codespace is created.",
+  "seed.note.off": "The repository is empty and “Initialize empty repositories” is off, so creation may fail.",
+  "apply.creating": "Creating the Codespace…",
+  "apply.creatingHint": "Creation usually takes 1–3 minutes.",
+  "apply.starting": "Starting the Codespace…",
+  "apply.registering": "Registering the DSH workspace…",
+  "apply.failed": "The operation failed: {message}",
+  "retry": "Retry",
+  "back": "Back",
+  "next": "Next",
+  "cancel": "Cancel",
+  "close": "Close",
+  "success.title": "The Codespace is ready",
+  "success.body": "The DSH workspace is registered; the session works inside the cloud Codespace.",
+  "success.open": "Open a session here",
+  "success.opening": "Opening…",
+  "success.openFailed": "That row is not in the sidebar yet. Expand the sidebar and use the “New session” button on the workspace row.",
+  "success.done": "Done",
+  "row.cloud": "Cloud Codespace workspace",
+  "row.hoverRepo": "{repo} · {name}",
+  "row.start": "Start Codespace",
+  "row.stop": "Pause Codespace",
+  "row.countdown": "Auto-pause in {n} min",
+  "row.countdownSoon": "Auto-pausing soon",
+  "row.pending": "Changing state…",
+  "row.error": "Unhealthy state: {state}",
+  "row.actionFailed": "The action failed: {message}",
+  "menu.delete": "Delete Codespace…",
+  "delete.title": "Delete Codespace",
+  "delete.body": "The cloud Codespace “{name}” is deleted permanently. Unpushed work inside it is lost and cannot be recovered. The DSH workspace record stays behind as an empty placeholder directory.",
+  "delete.confirm": "Delete permanently",
+  "delete.working": "Deleting…",
+  "delete.failed": "Delete failed: {message}",
+  "launcher.label": "New cloud workspace"
+}

package/locale/zh.json

@@ -0,0 +1,122 @@
+{
+  "nav": "Codespace",
+  "page.title": "Codespace",
+  "page.subtitle": "把 GitHub Codespace 当作 DSH 工作区：文件与命令工具在云端 Codespace 里运行。",
+  "status.heading": "状态",
+  "status.refresh": "刷新",
+  "status.checking": "检查中…",
+  "status.gh": "GitHub CLI (gh)",
+  "status.gh.installed": "已安装 · {version}",
+  "status.gh.missing": "未安装",
+  "status.gh.missingNote": "没有检测到 GitHub CLI。这不影响使用：插件会改用你在下面配置的 SSH 连接方式（推荐填 ~/.ssh/config 里的主机别名，例如 codespace-mybox）。安装 gh 后可以获得更完整的能力。",
+  "status.token": "GitHub 令牌",
+  "status.token.settings": "来自插件设置",
+  "status.token.env": "来自环境变量 GITHUB_TOKEN",
+  "status.token.gh": "来自 gh auth token",
+  "status.token.none": "未找到",
+  "status.token.noneNote": "未找到令牌：仓库列表与 Codespace 生命周期操作不可用。",
+  "status.login": "GitHub 登录",
+  "status.loggedOut": "未登录",
+  "status.configured": "配置",
+  "status.configured.yes": "已配置",
+  "status.configured.no": "未配置",
+  "status.failed": "状态读取失败：{message}",
+  "settings.heading": "设置",
+  "field.githubUsername": "GitHub 用户名",
+  "field.githubUsername.hint": "留空表示使用令牌所属的账号。",
+  "field.defaultBranch": "默认分支",
+  "field.autoPauseMinutes": "自动暂停等待时间（分钟）",
+  "field.autoPauseMinutes.hint": "一个回合结束后开始计时，期间收到新消息会取消。填 0 表示不自动暂停。双击工作区行上的时钟图标可以立即暂停。",
+  "field.sshKeyPath": "SSH 密钥（可选）",
+  "field.sshKeyPath.hint": "没有 gh 时用它连接 Codespace。填 ~/.ssh/config 里的主机别名，例如 codespace-mybox（私钥请在 Host 条目里用 IdentityFile 指定——只填密钥路径无法确定要连接哪台主机）。",
+  "field.sshKeyPath.set": "已设置",
+  "field.sshKeyPath.unset": "未设置",
+  "field.sshKeyPath.write": "输入新的值（保存后不再显示）",
+  "field.sshKeyPath.save": "保存",
+  "field.sshKeyPath.clear": "清除",
+  "field.alwaysShowCloudButton": "始终显示云端工作区按钮",
+  "field.alwaysShowCloudButton.hint": "关闭时，按钮只在鼠标悬停该工作区行时出现。开启后该行的整组操作按钮会常驻显示（CSS 无法只显示其中的一个子元素）。",
+  "field.autoInitEmptyRepo": "自动初始化空仓库",
+  "field.autoInitEmptyRepo.hint": "仓库没有任何提交时，先提交一个 README 再创建 Codespace。",
+  "field.readmeContent": "README 初始内容",
+  "field.readmeContent.hint": "留空则提交一个空的 README.md。",
+  "save": "保存",
+  "saving": "保存中…",
+  "saved": "已保存",
+  "saveFailed": "保存失败：{message}",
+  "managed.heading": "云端工作区",
+  "managed.empty": "还没有由本插件管理的 Codespace 工作区。",
+  "managed.loading": "正在读取…",
+  "managed.new": "新建云端工作区",
+  "managed.delete": "删除 Codespace…",
+  "managed.deleteFallbackNote": "侧边栏工作区行的「⋯」菜单里也有「删除 Codespace…」。如果那里没有出现，可以用这里的按钮。",
+  "window.title": "新建云端工作区",
+  "step.repo": "选择仓库",
+  "step.codespace": "选择 Codespace",
+  "step.machine": "选择机型",
+  "step.apply": "创建",
+  "step.done": "完成",
+  "repo.search": "搜索仓库",
+  "repo.loading": "正在读取仓库…",
+  "repo.empty": "没有匹配的仓库。",
+  "repo.failed": "仓库读取失败：{message}",
+  "repo.private": "私有",
+  "repo.isEmpty": "空仓库",
+  "repo.count": "共 {n} 个",
+  "cs.heading": "该仓库已有 Codespace",
+  "cs.pick": "选择一个 Codespace",
+  "cs.none": "该仓库还没有 Codespace，将新建一个。",
+  "cs.loading": "正在读取 Codespace…",
+  "cs.failed": "Codespace 读取失败：{message}",
+  "cs.state": "状态：{state}",
+  "cs.createNew": "新建一个 Codespace",
+  "prebuild.checking": "正在检查预构建…",
+  "prebuild.missing": "未配置预构建，创建可能较慢",
+  "prebuild.unknown": "无法确认预构建状态，创建可能需要 1–3 分钟",
+  "prebuild.cancel": "取消",
+  "prebuild.proceed": "直接创建",
+  "prebuild.ok": "该仓库已配置预构建。",
+  "machine.heading": "选择机型",
+  "machine.loading": "正在读取机型…",
+  "machine.failed": "机型读取失败：{message}",
+  "machine.empty": "该仓库没有可用的机型。",
+  "machine.default": "默认最小",
+  "machine.cpus": "{n} 核",
+  "machine.memory": "{n} GB 内存",
+  "machine.storage": "{n} GB 存储",
+  "machine.gpu": "GPU",
+  "seed.note": "仓库为空：将先提交 README.md，再创建 Codespace。",
+  "seed.note.off": "仓库为空，但「自动初始化空仓库」已关闭，创建可能失败。",
+  "apply.creating": "正在创建 Codespace…",
+  "apply.creatingHint": "创建通常需要 1–3 分钟。",
+  "apply.starting": "正在启动 Codespace…",
+  "apply.registering": "正在登记 DSH 工作区…",
+  "apply.failed": "操作失败：{message}",
+  "retry": "重试",
+  "back": "上一步",
+  "next": "下一步",
+  "cancel": "取消",
+  "close": "关闭",
+  "success.title": "Codespace 已就绪",
+  "success.body": "DSH 工作区已登记，会话的工作目录是云端 Codespace。",
+  "success.open": "在此打开会话",
+  "success.opening": "正在打开…",
+  "success.openFailed": "侧边栏里还没有这一行，请展开侧边栏后点击该工作区右侧的「新建会话」。",
+  "success.done": "完成",
+  "row.cloud": "云端 Codespace 工作区",
+  "row.hoverRepo": "{repo} · {name}",
+  "row.start": "启动 Codespace",
+  "row.stop": "暂停 Codespace",
+  "row.countdown": "还剩 {n} 分钟自动暂停",
+  "row.countdownSoon": "即将自动暂停",
+  "row.pending": "正在切换状态…",
+  "row.error": "状态异常：{state}",
+  "row.actionFailed": "操作失败：{message}",
+  "menu.delete": "删除 Codespace…",
+  "delete.title": "删除 Codespace",
+  "delete.body": "将永久删除云端 Codespace「{name}」。其中未推送的改动会一起丢失，且无法恢复。DSH 里保留的工作区记录只包含一个空的占位目录。",
+  "delete.confirm": "永久删除",
+  "delete.working": "正在删除…",
+  "delete.failed": "删除失败：{message}",
+  "launcher.label": "新建云端工作区"
+}

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "dsh-codespace-workspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Use a GitHub Codespace directly as a DSH workspace: the agent reads, writes and runs commands inside the cloud Codespace.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ckarefulon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ckarefulon/dsh-codespace-workspace.git"
+  },
+  "homepage": "https://github.com/Ckarefulon/dsh-codespace-workspace#readme",
+  "bugs": {
+    "url": "https://github.com/Ckarefulon/dsh-codespace-workspace/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/en.json": "./locale/en.json",
+    "./locale/zh.json": "./locale/zh.json"
+  },
+  "files": [
+    "lib",
+    "locale",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "icon": "./icon.svg",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node test/check.mjs && node test/shutdown.mjs && node test/e2e.mjs",
+    "test:node": "node test/check.mjs",
+    "test:shutdown": "node test/shutdown.mjs",
+    "test:e2e": "node test/e2e.mjs",
+    "test:live": "node test/live.mjs",
+    "test:browser": "node test/serve.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "codespace",
+    "codespaces",
+    "github",
+    "remote-workspace"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0 <5",
+    "@deepseek-ai/schemastery": ">=3.18.0 <4"
+  },
+  "meta": {
+    "title": "Codespace 云端工作区",
+    "description": "把 GitHub Codespace 当作 DSH 工作区：Agent 在云端 Codespace 里读写文件、执行命令。"
+  },
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.2.0-rc.2"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  }
+}