@petercjl/ecom-cli 0.0.0-bootstrap.0 → 0.1.1

package/INSTALL.md

@@ -0,0 +1,13 @@
+# Install for the current Agent
+
+User prompt: “帮我安装 @petercjl/ecom-cli，并安装它的配套 Skill。”
+
+## Agent bootstrap contract
+
+1. Resolve an available Node.js 22+ runtime from the current Agent's environment/configuration or PATH. Resolve that Agent's exact Skill directory from its advertised host configuration. Arbitrary valid Agent names use the generic adapter; do not infer another Agent's directory.
+2. Acquire the requested public npm package using the supported package manager. `npm install -g @petercjl/ecom-cli` provides the bootstrap CLI. This is partial installation until the Skill is installed. With scripts disabled, follow the same explicit steps below; postinstall is only a notice.
+3. Discover `ecom-cli capabilities --json` and `ecom-cli skill source --json`. Use the declared exact-target contract: `ecom-cli skill install --agent <current-agent-name> --target <absolute-skill-directory> --json`. The directory is the Skill itself, not its parent. Source code and accounts are not copied from the browser.
+4. Verify `current=true`, `managed=true`, `edited=false`, SHA-256 verification, package version and returned CLI entry. Load the installed `SKILL.md` through the current Agent's own discovery mechanism; refresh discovery if the host requires it. Installation is complete only after both package integrity and host discovery succeed.
+5. Use the returned isolated `.runtime/bin/ecom-cli.mjs` with Node.js for subsequent calls. The bootstrap npm package may then be removed; this Skill and runtime remain functional. A system Node.js runtime and the separately installed Ecom browser are declared external dependencies.
+
+Existing unmanaged or edited destinations are preserved and produce a structured conflict. Choose an unused destination or reconcile user edits with a backup. Never install other Agents merely because their directories exist. Runtime support is capability-based; current real browser validation is macOS. No prior published updater exists for this first release.

package/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -1,3 +1,29 @@
-# Ecom CLI bootstrap
+# Ecom CLI
 
-Minimal package reservation for Trusted Publishing setup. Functional stable releases are published separately through GitHub Actions.
+Agent CLI and portable Skill for the Ecom desktop browser. The first release lists the names and stable IDs of existing containers without opening websites or switching tabs. Ecom must already be running in normal desktop mode. The browser transport currently supports macOS; Windows browser integration is not implemented.
+
+## Install
+
+Send to your current Agent:
+
+> 帮我安装 @petercjl/ecom-cli，并安装它的配套 Skill。
+
+The Agent needs local Node.js 22+ and terminal/file access. Installation includes the CLI and an isolated copy of the Skill in that Agent's own resolved Skill directory. See [INSTALL.md](INSTALL.md) for the bootstrap contract, including installation with npm scripts disabled.
+
+## Use
+
+> 用 Ecom CLI 列出我当前的浏览器容器。
+
+Container names may identify accounts. Use a trusted Agent and share results intentionally. Installing the plugin does not authorize website operations, cookie export or account modification.
+
+## Update
+
+> 帮我更新 @petercjl/ecom-cli 和它的配套 Skill。
+
+Task entry checks stable `latest` at most daily, with a 1.5 second bound. Detection only notifies; updating requires authorization. An offline check retains the installed runtime. Each selected Skill contains its own complete CLI runtime; activate the entry returned by the installer. Other Agents remain independent. See [UPDATE.md](UPDATE.md).
+
+## Developer contract
+
+`ecom-cli help --json`, `version --json`, `capabilities --json`, `schema --json`, and `doctor --json` expose supported commands and versioned results. Errors use JSON with stable codes; exit code 2 means invalid arguments, 1 means operational failure. stdout contains results; stderr contains diagnostics. Multiple Ecom instances require explicit `--profile` or `--instance` selection. Connection authenticates through owner-only local mailbox files, verifies the live Ecom executable, and uses no remote debugging port.
+
+The browser owns sessions, containers and authorization. This package owns discovery, read-only transport and managed installation. The Skill documents invocation, diagnosis and recovery. Additional browser capabilities will extend this same command/Skill contract.

package/UPDATE.md

@@ -0,0 +1,11 @@
+# Update the selected Agent installation
+
+User prompt: “帮我更新 @petercjl/ecom-cli 和它的配套 Skill。”
+
+Resolve the currently selected Agent and exact Skill destination before mutation. Inspect the declared command contract and managed status. When current, reuse the verified installation; a same-version update repairs a missing or stale unedited Skill.
+
+Run the selected Skill's isolated CLI with `update install --agent <name> --target <absolute-skill-directory> --yes --json`. It selects stable `latest` (or an explicit stable `--version`), acquires the candidate through npm with scripts disabled, stages the full runtime plus Skill, preserves the previous target as a uniquely named backup, activates and verifies hashes/version. Use the new receipt's entry. The optional global bootstrap package remains independently installed; it is not the selected Agent runtime. Refresh host discovery and load the resulting Skill before reporting completion.
+
+Acquisition records a target-scoped operation journal and retains candidate location, requested version and previous version. For failure, inspect the journal and `skill status` before any new attempt. A directory lock, local edits or unmanaged target stops replacement. Failed rename restores the previous directory when possible and reports recovery evidence. Retain backups and candidates until an authorized cleanup. To roll back, verify a recorded backup, preserve the current target and restore that backup as an explicit maintenance action; do not overwrite user content.
+
+Automatic checks occur only at container-list task entry, use `latest`, are throttled to 24 hours and bounded to 1500 ms. Set `ECOM_CLI_UPDATE_CHECK=0` to disable checks. An unavailable registry does not block browser reads or replace an installation. Updates affect only the explicit target; other Agents' isolated copies continue independently. External Node.js and Ecom installation remain unchanged.

package/bin/ecom-cli.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {main} from '../lib/cli.mjs';
+try {
+  const result = await main(process.argv.slice(2));
+  process.stdout.write(JSON.stringify(result) + '\n');
+} catch (error) {
+  process.stdout.write(JSON.stringify({ok:false,error:{code:error.code || 'CLI_ERROR',message:error.code ? error.message : 'Operation failed; inspect doctor and operation status',executed:error.executed ?? false,...(error.operationId ? {operationId:error.operationId} : {}),...(error.recovery ? {recovery:error.recovery} : {})}}) + '\n');
+  process.exitCode = error.code === 'INVALID_ARGUMENT' ? 2 : 1;
+}

package/capabilities.json

@@ -0,0 +1,345 @@
+{
+  "schemaVersion": 1,
+  "package": "@petercjl/ecom-cli",
+  "version": "0.1.1",
+  "skills": [
+    "ecom-cli"
+  ],
+  "commandContracts": {
+    "help": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "version": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "capabilities": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "schema": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "doctor": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "containers list": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Read container IDs and names; authenticated local request and throttled update cache only"
+    },
+    "skill source": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--name": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill status": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--target": {
+          "type": "string"
+        },
+        "--name": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill install": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--target": {
+          "type": "string"
+        },
+        "--name": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "skill update": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--target": {
+          "type": "string"
+        },
+        "--name": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "update check": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "update install": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--target": {
+          "type": "string"
+        },
+        "--name": {
+          "type": "string"
+        },
+        "--version": {
+          "type": "string"
+        },
+        "--yes": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "package-and-skill-update"
+    }
+  },
+  "transport": {
+    "kind": "private-local-mailbox",
+    "protocolVersion": 1,
+    "debuggingRequired": false,
+    "platforms": {
+      "macos": "implemented",
+      "windows": "unsupported"
+    }
+  },
+  "discoveryContract": {
+    "schemaVersion": 1,
+    "commandsField": "commandContracts",
+    "entryPoints": [
+      {
+        "argv": [
+          "capabilities",
+          "--json"
+        ],
+        "result": "manifest"
+      }
+    ],
+    "version": {
+      "command": "version",
+      "argv": [
+        "version",
+        "--json"
+      ],
+      "fields": {
+        "package": {
+          "field": "package",
+          "type": "string"
+        },
+        "version": {
+          "field": "version",
+          "type": "string"
+        }
+      }
+    },
+    "skillCollection": {
+      "namesField": "skills",
+      "default": "ecom-cli",
+      "selector": {
+        "option": "--name",
+        "type": "string"
+      },
+      "enumeration": {
+        "argv": [
+          "skill",
+          "source",
+          "--json"
+        ],
+        "itemsField": "items",
+        "completeField": "complete"
+      },
+      "namedSource": [
+        "skill",
+        "source",
+        "--name",
+        "{skill}",
+        "--json"
+      ]
+    }
+  },
+  "maintenanceContract": {
+    "schemaVersion": 1,
+    "agentEligibility": "valid-name-with-generic-fallback",
+    "hostDiscoveryAuthority": "host",
+    "targetOptions": {
+      "--target": {
+        "kind": "skill-directory"
+      }
+    },
+    "source": {
+      "name": {
+        "field": "name",
+        "type": "string"
+      },
+      "package": {
+        "field": "package",
+        "type": "string"
+      },
+      "version": {
+        "field": "version",
+        "type": "string"
+      },
+      "path": {
+        "field": "path",
+        "type": "string"
+      }
+    },
+    "status": {
+      "name": {
+        "field": "name",
+        "type": "string"
+      },
+      "package": {
+        "field": "package",
+        "type": "string"
+      },
+      "version": {
+        "field": "version",
+        "type": "string"
+      },
+      "target": {
+        "field": "target",
+        "type": "string"
+      },
+      "installed": {
+        "field": "installed",
+        "type": "boolean"
+      },
+      "managed": {
+        "field": "managed",
+        "type": "boolean"
+      },
+      "current": {
+        "field": "current",
+        "type": "boolean"
+      },
+      "edited": {
+        "field": "edited",
+        "type": "boolean"
+      },
+      "verification": {
+        "field": "verification",
+        "type": "object"
+      },
+      "recovery": {
+        "field": "recovery",
+        "type": "object"
+      }
+    }
+  },
+  "installationLifecycle": {
+    "skillRequired": true,
+    "updateRequiresSkillSync": true,
+    "required_components": [
+      "cli",
+      "skill"
+    ],
+    "agentNeutral": true,
+    "targetRequired": true,
+    "hostRegistrationRequired": true,
+    "installationMode": "copy",
+    "sharedLinksAllowed": false,
+    "isolatedRuntimeRequired": true,
+    "installGuide": "INSTALL.md",
+    "updateGuide": "UPDATE.md",
+    "install": "Resolve current Agent exact Skill target; run skill install --agent NAME --target PATH; load Skill through host discovery.",
+    "update": "Run selected Skill runtime update install --agent NAME --target PATH --yes; verify returned activated entry and refresh host discovery.",
+    "verification": "Verify CLI and Skill versions, managed hashes and current=true; host loads installed SKILL.md independently."
+  },
+  "automaticUpdates": {
+    "enabledByDefault": true,
+    "intervalHours": 24,
+    "timeoutMs": 1500,
+    "trigger": "containers list task entry",
+    "configuration": "Stable latest channel; detection only. Explicit update activates only the selected target runtime and Skill together.",
+    "disable": "ECOM_CLI_UPDATE_CHECK=0",
+    "recovery": "Offline checks retain installed runtime; local edit/ownership conflicts stop replacement; prior target kept as backup. Use recorded candidate and inspect target status before retrying.",
+    "defaultMode": "notify"
+  },
+  "compatibility": {
+    "agents": "Any Agent with terminal, Node.js and Skill discovery capabilities; generic adapter",
+    "macos": "Runtime validation pending",
+    "windows": "Package mechanics only; browser transport unsupported",
+    "historicalUpdater": "First release; registry package absent; no prior updater exists"
+  },
+  "errors": [
+    "INSTANCE_NOT_RUNNING",
+    "INSTANCE_AMBIGUOUS",
+    "INSTANCE_CHANGED",
+    "UNSAFE_ENDPOINT",
+    "OPERATION_TIMEOUT",
+    "PROTOCOL_MISMATCH",
+    "PLATFORM_UNSUPPORTED",
+    "TARGET_REQUIRED",
+    "LOCAL_EDITS",
+    "UNMANAGED_TARGET",
+    "TARGET_LOCKED"
+  ]
+}

package/lib/browser.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import {setTimeout as pause} from 'node:timers/promises';
+import {fail,privatePath,writeNew,exists} from './common.mjs';
+const ps=(args)=>execFileSync('/bin/ps',args,{encoding:'utf8',timeout:3000,maxBuffer:4*1024*1024});
+export function discover({profile,instance}={}) {
+  if(process.platform!=='darwin') throw fail('PLATFORM_UNSUPPORTED','Browser transport currently supports macOS; no debugging fallback is available');
+  const candidates=[];
+  for(const line of ps(['-axo','pid=,uid=,comm=']).split('\n')) {
+    const m=line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+    if(!m || Number(m[2])!==process.getuid() || !/\/(Ecom Dev|Ecom)\.app\/Contents\/MacOS\/\1$/.test(m[3])) continue;
+    let command; try {command=ps(['-ww','-p',m[1],'-o','command=']).trim();}catch{continue;}
+    if(/--(?:remote-debugging|headless|enable-automation)/.test(command)) continue;
+    const selected=command.match(/(?:^| )--user-data-dir=(.*?)(?= --|$)/)?.[1];
+    if(!selected || !path.isAbsolute(selected) || (profile && path.resolve(profile)!==path.resolve(selected))) continue;
+    const folder=path.join(selected,'Default','.ecom-native-cli'), file=path.join(folder,'endpoint.json');
+    if(!exists(file)) continue;
+    privatePath(folder,true);privatePath(file);
+    const endpoint=JSON.parse(fs.readFileSync(file,'utf8'));
+    if(endpoint.product!=='Ecom' || endpoint.schemaVersion!==1 || endpoint.pid!==Number(m[1]) || endpoint.executable!==m[3] || endpoint.userDataDir!==selected || !/^[\da-f-]{36}$/.test(endpoint.instanceId) || typeof endpoint.authToken!=='string') continue;
+    if(instance && endpoint.instanceId!==instance) continue;
+    candidates.push({folder,endpoint,channel:m[3].includes('/Ecom Dev.app/')?'dev':'stable'});
+  }
+  if(candidates.length!==1) throw fail(candidates.length?'INSTANCE_AMBIGUOUS':'INSTANCE_NOT_RUNNING',candidates.length?'Multiple Ecom instances; specify --profile or --instance':'Open an Ecom build supporting this CLI in normal desktop mode');
+  return candidates[0];
+}
+export async function listContainers(options={}) {return readMailbox(discover(options));}
+export async function readMailbox({folder,endpoint,channel},timeoutMs=10000) {
+  privatePath(folder,true);privatePath(path.join(folder,'endpoint.json'));
+  const current=JSON.parse(fs.readFileSync(path.join(folder,'endpoint.json'),'utf8'));
+  if(current.pid!==endpoint.pid || current.instanceId!==endpoint.instanceId || current.authToken!==endpoint.authToken) throw fail('INSTANCE_CHANGED','Instance changed before submission; discover it again');
+  const id=crypto.randomUUID(), request=path.join(folder,id+'.request.json'), temporary=path.join(folder,id+'.request.tmp'), response=path.join(folder,id+'.response.json');
+  if(exists(request)||exists(response)) throw fail('OPERATION_COLLISION','Request already exists');
+  writeNew(temporary,{schemaVersion:1,instanceId:endpoint.instanceId,authToken:endpoint.authToken,method:'containers.list'});
+  fs.renameSync(temporary,request);
+  const end=Date.now()+timeoutMs;
+  while(Date.now()<end) {
+    if(exists(response)) {
+      privatePath(response);
+      const raw=fs.readFileSync(response,'utf8');
+      if(Buffer.byteLength(raw)>1024*1024) throw fail('PROTOCOL_MISMATCH','Oversized response',{operationId:id,executed:'unknown'});
+      let body;try{body=JSON.parse(raw);}catch{await pause(25);continue;}
+      if(body.schemaVersion!==1 || body.instanceId!==endpoint.instanceId || body.operationId!==id) throw fail('PROTOCOL_MISMATCH','Response does not match this operation',{operationId:id,executed:'unknown'});
+      fs.unlinkSync(response);
+      if(body.ok!==true) throw fail('BROWSER_ERROR','Browser refused read-only request',{operationId:id,executed:body.error?.executed??false});
+      if(!Array.isArray(body.containers)||body.containers.some(c=>typeof c.id!=='string'||typeof c.name!=='string')) throw fail('PROTOCOL_MISMATCH','Invalid container list',{operationId:id,executed:'unknown'});
+      return {ok:true,schemaVersion:1,operationId:id,instance:{id:endpoint.instanceId,pid:endpoint.pid,channel},containers:body.containers.map(({id,name})=>({id,name}))};
+    }
+    await pause(25);
+  }
+  throw fail('OPERATION_TIMEOUT','Read timed out; retain operation ID and inspect instance before retrying',{operationId:id,executed:'unknown'});
+}

package/lib/cli.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {root,pkg,fail} from './common.mjs';
+import {discover,listContainers} from './browser.mjs';
+import {source,status,installSkill,checkUpdate,updateInstall} from './maintenance.mjs';
+export const capabilities=()=>JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
+export function parse(argv) {
+  const positions=[],options={}, caps=capabilities();
+  for(let i=0;i<argv.length;i++) {
+    const word=argv[i];
+    if(!word.startsWith('--')) {positions.push(word);continue;}
+    if(word==='--version'&&argv.length===1){positions.push('version');continue;}
+    const key=word.slice(2);
+    if(Object.hasOwn(options,key)) throw fail('INVALID_ARGUMENT','Duplicate option '+word);
+    if(['json','help','yes'].includes(key))options[key]=true;
+    else if(['agent','target','profile','instance','name','version'].includes(key)&&argv[i+1]&&!argv[i+1].startsWith('--')) options[key]=argv[++i];
+    else throw fail('INVALID_ARGUMENT','Unknown option or missing value: '+word);
+  }
+  let command=positions.join(' ')||'help';
+  const requested=command;
+  if(options.help) command='help';
+  if(!caps.commandContracts[command]) throw fail('INVALID_ARGUMENT','Unsupported command; use help --json');
+  if(command!=='help')for(const key of Object.keys(options))if(!caps.commandContracts[command].options['--'+key])throw fail('INVALID_ARGUMENT','Option is not supported by this command: --'+key);
+  if(options.name&&options.name!=='ecom-cli')throw fail('INVALID_ARGUMENT','Unknown Skill name');
+  return {command,options,requested};
+}
+export async function main(argv) {
+  const {command,options,requested}=parse(argv);
+  if(command==='help')return {ok:true,package:pkg.name,version:pkg.version,usage:'ecom-cli containers list --json | skill source|status|install|update | update check|install | doctor',...capabilities(),...(capabilities().commandContracts[requested]??{})};
+  if(command==='version')return {ok:true,package:pkg.name,version:pkg.version,protocolVersion:1};
+  if(command==='capabilities'||command==='schema')return {ok:true,...capabilities()};
+  if(command==='skill source') {const item=source();return {...capabilities(),...item,complete:true,items:[item]};}
+  if(command==='skill status')return status(options);
+  if(command==='skill install'||command==='skill update')return installSkill(options);
+  if(command==='update check')return checkUpdate();
+  if(command==='update install')return updateInstall(options);
+  if(command==='doctor') {
+    let instance,error;try{const found=discover(options);instance={id:found.endpoint.instanceId,pid:found.endpoint.pid,channel:found.channel};}catch(e){error={code:e.code,message:e.message};}
+    return {ok:!error,package:pkg.name,version:pkg.version,node:process.version,platform:process.platform,transport:'private-local-mailbox',debuggingRequired:false,instance,...(error?{error}:{}),skillSource:source().path};
+  }
+  if(command==='containers list') {
+    const update=await checkUpdate({automatic:true});
+    if(update.available)process.stderr.write('Ecom CLI update available: '+update.latest+'; ask the current Agent to update the package and Skill.\n');
+    return listContainers(options);
+  }
+}

package/lib/common.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+export const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const pkg = JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
+export const fail = (code,message,extra={}) => Object.assign(new Error(message),{code,...extra});
+export function exists(p) { try { fs.lstatSync(p); return true; } catch(e) { if(e.code==='ENOENT') return false; throw e; } }
+export function tree(dir, prefix='') {
+  const out={};
+  for(const item of fs.readdirSync(dir,{withFileTypes:true}).sort((a,b)=>a.name.localeCompare(b.name))) {
+    if(item.name==='.ecom-receipt.json' || item.name==='.ecom-operation.json') continue;
+    const rel=prefix+item.name, p=path.join(dir,item.name), st=fs.lstatSync(p);
+    if(st.isSymbolicLink() || (!st.isDirectory() && (!st.isFile() || st.nlink!==1))) throw fail('UNSAFE_PATH','Shared links and special files are not supported');
+    if(st.isDirectory()) Object.assign(out,tree(p,rel+'/'));
+    else out[rel]=crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+  }
+  return out;
+}
+export function writeNew(p,data) { fs.writeFileSync(p,JSON.stringify(data,null,2)+'\n',{flag:'wx',mode:0o600}); }
+export function privatePath(p,directory=false) {
+  const s=fs.lstatSync(p);
+  if(s.uid!==process.getuid?.() || (s.mode&0o777)!==(directory?0o700:0o600) || (directory?!s.isDirectory():!s.isFile()||s.nlink!==1)) throw fail('UNSAFE_ENDPOINT','Endpoint ownership, permissions or file type is invalid');
+}

package/lib/maintenance.mjs

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {root,pkg,fail,exists,tree,writeNew} from './common.mjs';
+const receiptName='.ecom-receipt.json';
+export const source=(base=root)=>({ok:true,name:'ecom-cli',package:pkg.name,version:JSON.parse(fs.readFileSync(path.join(base,'package.json'),'utf8')).version,path:path.join(base,'skills/ecom-cli'),provenance:{ownership:'npm-package',registryContentVerified:false}});
+export function targetOf(options) {
+  if(!options.agent || !/^[a-z][a-z0-9-]{0,63}$/.test(options.agent)) throw fail('INVALID_ARGUMENT','Supply a valid --agent name; unnamed hosts use the generic adapter');
+  if(!options.target || !path.isAbsolute(options.target)) throw fail('TARGET_REQUIRED','Current Agent must resolve and supply an absolute --target Skill directory');
+  const target=path.resolve(options.target);
+  for(let p=target;p!==path.dirname(p);p=path.dirname(p)) if(exists(p)&&fs.lstatSync(p).isSymbolicLink()) {
+    const systemAlias=process.platform==='darwin'&&['/var','/tmp'].includes(p)&&fs.lstatSync(p).uid===0;
+    if(!systemAlias)throw fail('UNSAFE_PATH','Skill destination must use physical directories');
+  }
+  const ownTarget=path.basename(root)==='.runtime'&&path.dirname(root)===target;
+  if(!ownTarget&&(target===root || root.startsWith(target+path.sep) || target.startsWith(root+path.sep))) throw fail('TARGET_CONFLICT','Skill target must be independent of the package source');
+  return target;
+}
+export function status(options,base=root) {
+  const target=targetOf(options), meta=path.join(target,receiptName), installed=exists(target);
+  let receipt;try{if(exists(meta)&&fs.lstatSync(meta).isFile()) receipt=JSON.parse(fs.readFileSync(meta,'utf8'));}catch{}
+  const managed=receipt?.package===pkg.name && receipt?.target===target && receipt?.agent===options.agent;
+  const files=installed?tree(target):{}, old=managed?receipt.files:{}, edited=managed && JSON.stringify(files)!==JSON.stringify(old);
+  const identity=source(base), canonical=tree(identity.path);
+  const canonicalCurrent=managed && Object.entries(canonical).every(([name,hash])=>files[name]===hash) && Object.keys(files).filter(n=>!n.startsWith('.runtime/')).length===Object.keys(canonical).length;
+  let runtimeVersion;try{runtimeVersion=JSON.parse(fs.readFileSync(path.join(target,'.runtime/package.json'),'utf8')).version;}catch{}
+  const current=!!(managed&&!edited&&canonicalCurrent&&runtimeVersion===identity.version&&receipt.version===identity.version);
+  return {...identity,target,installed,managed,current,edited:!!edited,adapter:'generic',agent:options.agent,entry:path.join(target,'.runtime/bin/ecom-cli.mjs'),verification:{verified:current,algorithm:'sha256'},recovery:{required:installed&&!current,action:edited?'Preserve local edits; reconcile them before update':'Run skill update for this exact target'},hostDiscovery:{authority:'host',verified:false},...(managed?{installedVersion:receipt.version,backup:receipt.backup??null}:{})};
+}
+export function installSkill(options,base=root) {
+  const before=status(options,base), target=before.target;
+  if(before.current) return {...before,changed:false};
+  if(before.installed&&!before.managed) throw fail('UNMANAGED_TARGET','Existing Skill is user-owned; choose a fresh destination');
+  if(before.edited) throw fail('LOCAL_EDITS','Managed Skill has local edits; preserve and reconcile them before update');
+  const parent=path.dirname(target);fs.mkdirSync(parent,{recursive:true});
+  const lock=target+'.ecom-lock';let fd;
+  try {fd=fs.openSync(lock,'wx',0o600);}catch{throw fail('TARGET_LOCKED','Another maintenance operation holds the target lock');}
+  const operationId=crypto.randomUUID(), staging=target+'.ecom-stage-'+operationId;
+  const backup=before.installed?target+'.ecom-backup-'+operationId:null;
+  let activated=false;
+  try {
+    tree(base);
+    fs.cpSync(source(base).path,staging,{recursive:true,errorOnExist:true,force:false});
+    const runtime=path.join(staging,'.runtime');fs.mkdirSync(runtime);
+    for(const name of ['package.json','capabilities.json','bin','lib','scripts','skills','README.md','INSTALL.md','UPDATE.md','LICENSE']) {
+      fs.cpSync(path.join(base,name),path.join(runtime,name),{recursive:true,errorOnExist:true,force:false});
+    }
+    const manifest=source(base);
+    writeNew(path.join(staging,receiptName),{schemaVersion:1,package:pkg.name,name:'ecom-cli',version:manifest.version,target,agent:options.agent,operationId,backup,files:tree(staging)});
+    // Recheck edits after staging, before replacement.
+    const again=status(options,base);
+    if(again.edited || again.installed!==before.installed) throw fail('TARGET_CHANGED','Skill changed during preparation');
+    if(backup) fs.renameSync(target,backup);
+    try {fs.renameSync(staging,target);activated=true;}catch(e){if(backup&&!exists(target))fs.renameSync(backup,target);throw e;}
+    const result=status(options,base);
+    if(!result.current) throw fail('VERIFY_FAILED','Installation integrity verification failed');
+    return {...result,changed:true,operationId,backup,completion:{cli:true,skill:true,hostDiscovery:false},remainingActions:['Load installed SKILL.md through the current Agent discovery mechanism']};
+  } catch(e) {
+    if(!activated&&exists(staging)) fs.rmSync(staging,{recursive:true});
+    throw fail(e.code||'INSTALL_FAILED',e.code?e.message:'Skill activation failed; the previous installation is preserved',{operationId,recovery:{backup,target,activated,action:'Inspect skill status before retrying'}});
+  } finally {fs.closeSync(fd);fs.unlinkSync(lock);}
+}
+const cacheRoot=()=>path.join(os.homedir(),'.cache','ecom-cli');
+export async function checkUpdate({automatic=false}={}) {
+  if(automatic&&process.env.ECOM_CLI_UPDATE_CHECK==='0') return {ok:true,disabled:true};
+  const cache=path.join(cacheRoot(),'update.json');
+  let old;try {old=JSON.parse(fs.readFileSync(cache,'utf8'));}catch{}
+  if(automatic&&old?.version===pkg.version&&Date.now()-old.checkedAt<86400000) return {...old,cached:true};
+  let result;
+  try {
+    const response=await fetch('https://registry.npmjs.org/@petercjl%2fecom-cli/latest',{signal:AbortSignal.timeout(1500)});
+    if(!response.ok) throw Error('registry');
+    const data=await response.json();if(data.name!==pkg.name||!/^\d+\.\d+\.\d+$/.test(data.version))throw Error('shape');
+    result={ok:true,version:pkg.version,latest:data.version,available:data.version!==pkg.version,checkedAt:Date.now(),channel:'latest'};
+  }catch{result={ok:false,code:'REGISTRY_UNAVAILABLE',version:pkg.version,checkedAt:Date.now(),retained:true};}
+  if(automatic) {
+    try {fs.mkdirSync(cacheRoot(),{recursive:true,mode:0o700});if(!exists(cache))writeNew(cache,result);else {const archive=cache+'.previous-'+crypto.randomUUID();fs.renameSync(cache,archive);writeNew(cache,result);}}catch{/* Detection must not block read-only work. */}
+  }
+  return result;
+}
+export async function updateInstall(options) {
+  const before=status(options);
+  if(before.installed&&(!before.managed||before.edited)) throw fail('LOCAL_EDITS','Resolve target ownership and edits before updating');
+  if(!options.yes) throw fail('CONFIRMATION_REQUIRED','Explicit update authorization requires --yes');
+  const selected=options.version??(await checkUpdate()).latest;
+  if(!/^\d+\.\d+\.\d+$/.test(selected??'')) throw fail('REGISTRY_UNAVAILABLE','Cannot resolve a stable version; installed components retained');
+  if(selected===pkg.version) return installSkill(options);
+  const directory=fs.mkdtempSync(path.join(os.tmpdir(),'ecom-cli-candidate-'));
+  const operationId=crypto.randomUUID();
+  const journal=options.target+'.ecom-update-'+operationId+'.json';
+  fs.mkdirSync(path.dirname(journal),{recursive:true});
+  writeNew(journal,{operationId,target:before.target,previousVersion:pkg.version,candidateVersion:selected,stage:'acquisition',candidate:directory});
+  const npm=process.platform==='win32'?'npm.cmd':'npm';
+  const acquired=spawnSync(npm,['install','--prefix',directory,'--ignore-scripts','--no-audit','--no-fund',pkg.name+'@'+selected],{encoding:'utf8',timeout:120000,shell:process.platform==='win32',env:{...process.env,npm_config_dry_run:'false',npm_config_json:'false'}});
+  if(acquired.status!==0) throw fail('PACKAGE_ACQUISITION_FAILED','Candidate installation failed; existing runtime and Skill retained',{operationId,recovery:{journal,stage:'acquisition',action:'Inspect candidate and operation record before retrying'}});
+  const candidate=path.join(directory,'node_modules/@petercjl/ecom-cli');
+  if(source(candidate).version!==selected) throw fail('VERSION_MISMATCH','Acquired candidate version differs from requested version',{operationId,recovery:{journal}});
+  const result=installSkill(options,candidate);
+  return {...result,operationId,journal,selectedVersion:selected,bootstrapRetained:true,activation:'Use the entry in this receipt; the selected Skill contains its own CLI runtime'};
+}

package/package.json

@@ -1 +1,37 @@
-{"name": "@petercjl/ecom-cli", "version": "0.0.0-bootstrap.0", "description": "Reserved Ecom CLI package for GitHub Actions Trusted Publishing setup", "license": "MPL-2.0", "files": ["README.md"], "publishConfig": {"access": "public"}, "repository": {"type": "git", "url": "git+https://github.com/petercjl/ecom.git"}}
+{
+  "name": "@petercjl/ecom-cli",
+  "version": "0.1.1",
+  "description": "Agent CLI and portable Skill for Ecom browser containers",
+  "type": "module",
+  "license": "MPL-2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "ecom-cli": "bin/ecom-cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "scripts",
+    "capabilities.json",
+    "INSTALL.md",
+    "UPDATE.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "postinstall": "node scripts/install-notice.mjs",
+    "prepack": "node scripts/validate.mjs",
+    "version": "node scripts/sync-version.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petercjl/ecom.git",
+    "directory": "packages/ecom-cli"
+  }
+}

package/scripts/install-notice.mjs

@@ -0,0 +1 @@
+process.stderr.write('Ecom CLI bootstrap installed. Complete CLI + Skill installation for your current Agent: discover ecom-cli skill source --json, resolve the exact Skill directory, run skill install --agent NAME --target PATH, then verify host discovery. See INSTALL.md.\n');

package/scripts/sync-version.mjs

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import {root,pkg} from '../lib/common.mjs';
+for(const name of ['capabilities.json','skills/ecom-cli/package.json']) {
+  const file=path.join(root,name), info=fs.lstatSync(file);
+  if(!info.isFile()||info.isSymbolicLink())throw Error('Unsafe version metadata');
+  const value=JSON.parse(fs.readFileSync(file,'utf8'));
+  const backup=path.join(os.tmpdir(),'ecom-version-backup-'+crypto.randomUUID());fs.copyFileSync(file,backup,fs.constants.COPYFILE_EXCL);
+  value.version=pkg.version;
+  fs.writeFileSync(file,JSON.stringify(value,null,2)+'\n');
+}

package/scripts/validate.mjs

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import {root,pkg,tree} from '../lib/common.mjs';
+const caps=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
+const skill=JSON.parse(fs.readFileSync(path.join(root,'skills/ecom-cli/package.json'),'utf8'));
+assert.equal(caps.version,pkg.version);assert.equal(skill.version,pkg.version);
+assert.equal(skill.name,pkg.name);assert.ok(fs.statSync(path.join(root,'skills/ecom-cli/SKILL.md')).size>100);
+tree(path.join(root,'skills')); // Reject shared links before packing.
+console.error('Version, Skill identity and physical resource checks passed: '+pkg.version);

package/skills/ecom-cli/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ecom-cli
+description: List isolated account containers in the running Ecom desktop browser, inspect its CLI connection, or install/update the Ecom CLI and companion Skill for the current Agent. Use when the user asks for Ecom browser containers or Ecom CLI setup. Website business queries and browser mutations are outside the first release.
+---
+
+# Ecom CLI
+
+## Input → strategy → output
+
+Input is a request to list Ecom containers, diagnose the connection, or maintain this plugin for the current Agent. The current Agent needs local command execution, file access and Node.js 22+. Output is a verified container list (stable ID and name), connection diagnosis, or an installation receipt with a separate host discovery check. Container names may identify accounts; disclose only within the user's request.
+
+## Main line
+
+1. Resolve this installed Skill's directory from the host's actual discovery record. Its bundled CLI is `.runtime/bin/ecom-cli.mjs` relative to that directory. Invoke it through an available Node.js 22+ runtime, checking host-managed runtime configuration before PATH. Canonical npm source has no `.runtime`; complete its managed installation using the packaged INSTALL.md first.
+2. Read [capabilities.json](capabilities.json) and use [the generic adapter](adapters/generic.json) for any host with the required capabilities. Probe the actual entry with `version --json` and `capabilities --json`; use only declared commands and flags. A missing runtime or required capability ends with CAPABILITY_UNAVAILABLE; do not modify adapters during a task.
+3. For normal listing, invoke the resolved entry with `containers list --json`. Ecom must already be running in normal desktop mode. Discovery validates the live executable and protected endpoint. With multiple instances, ask which instance/profile the user intends and pass the declared selector. Never choose an account from a name guess.
+4. Require `ok=true`, protocol version 1, a concrete instance identity and container ID/name pairs. Return the names and stable IDs as requested. This operation reads containers without navigating pages or changing the active tab.
+
+## Diagnosis and recovery
+
+- INSTANCE_NOT_RUNNING: run `doctor --json`. Ask the user to open a compatible Ecom version. Do not enable remote debugging or substitute another browser.
+- INSTANCE_AMBIGUOUS: obtain the intended instance or profile, then return to step 3.
+- INSTANCE_CHANGED: no request was submitted; rediscover before returning to step 3.
+- UNSAFE_ENDPOINT, PROTOCOL_MISMATCH or BROWSER_ERROR: stop and report the exact code. Preserve browser state and request identity.
+- OPERATION_TIMEOUT: retain the operation ID and report unknown completion. Inspect the instance and operation files under the protected endpoint before any retry; never blindly repeat an unknown operation.
+- PLATFORM_UNSUPPORTED: report the limitation. Browser integration currently supports macOS. Windows package mechanics and generic host format are separate from actual browser support.
+
+## Installation and update branch
+
+Enter this branch before business calls when the user requests installation or updates. Read the selected package's INSTALL.md / UPDATE.md from its discovered source, then return to main-line step 1 after maintenance.
+
+Resolve the current Agent's exact Skill destination from host configuration; use its actual name with the generic adapter. `skill source --json` identifies canonical bytes. `skill status --agent NAME --target PATH --json` verifies the selected target without writes. Use `skill install` or `skill update` with those declared flags for physical isolated copies; installed copies contain their own complete runtime. Installation covers both CLI and Skill; npm bootstrap success alone is partial.
+
+For an authorized package update, invoke the installed entry's `update install --agent NAME --target PATH --yes --json`. It acquires stable latest and activates CLI plus Skill together. Use the new entry from its receipt, verify CLI/Skill versions and SHA-256 `current=true`, then refresh and load this exact Skill through host discovery. Preserve receipts and backups. Local edits and unmanaged destinations require reconciliation before replacement; other Agent installations remain untouched. Automatic task-entry checks only notify; offline checks retain the installed runtime.
+
+## QA and evolution
+
+Success requires actual structured CLI output, not inferred browser state. Maintenance additionally requires integrity plus native host discovery. Runtime checks do not claim clean-context regression or other Agents/OS tests. Add new commands to the browser capability layer, CLI schema, tests and this canonical Skill together in an authorized development cycle. This simple deterministic Skill uses direct internalization of user-confirmed scope and verified CLI contracts; private knowledge bases are not runtime dependencies.

package/skills/ecom-cli/adapters/generic.json

@@ -0,0 +1,25 @@
+{
+  "platform": "generic",
+  "status": "implemented",
+  "mappings": [
+    {
+      "implementation": {
+        "kind": "cli",
+        "contract": "Current host terminal executes available Node.js with the discovered Skill-root .runtime/bin/ecom-cli.mjs"
+      },
+      "status": "implemented",
+      "discovery": "Current host resolves exact Skill directory and Node.js runtime; probe CLI version and capabilities",
+      "normalization": "Preserve ok, containers, instance and error from JSON; attach exit status to metadata",
+      "permissions": "Local execution; explicit selected-target maintenance authorization",
+      "limitations": "Browser transport currently macOS only; host discovery evidence is separate",
+      "capability_id": "command.execute",
+      "features": [
+        "local-node-runtime",
+        "structured-stdout",
+        "exit-code"
+      ]
+    }
+  ],
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0"
+}

package/skills/ecom-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ecom CLI"
+  short_description: "List isolated Ecom browser account containers"
+  default_prompt: "List my Ecom browser containers."

package/skills/ecom-cli/capabilities.json

@@ -0,0 +1,44 @@
+{
+  "schema_version": "1.0.0",
+  "target_platforms": [
+    "generic"
+  ],
+  "host_resolution": {
+    "fallback_adapter": "generic",
+    "authority": "host"
+  },
+  "capabilities": [
+    {
+      "id": "command.execute",
+      "purpose": "Run the isolated Ecom CLI",
+      "required": true,
+      "required_features": [
+        "local-node-runtime",
+        "structured-stdout",
+        "exit-code"
+      ],
+      "input_fields": [
+        "argv",
+        "skill_root"
+      ],
+      "output_fields": [
+        "ok",
+        "containers",
+        "instance",
+        "error"
+      ],
+      "side_effects": {
+        "external_mutation": false,
+        "may_cost_money": false,
+        "authorization": "Read-only browser request authorized by user; selected-target writes require installation/update intent"
+      },
+      "errors": [
+        "CAPABILITY_UNAVAILABLE",
+        "PLATFORM_UNSUPPORTED",
+        "INSTANCE_NOT_RUNNING"
+      ]
+    }
+  ],
+  "schema": "portable-skill-capabilities",
+  "skill": "ecom-cli"
+}

package/skills/ecom-cli/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@petercjl/ecom-cli",
+  "version": "0.1.1",
+  "private": true,
+  "type": "module"
+}