codex-auto-approve 0.1.1 → 0.2.0

package/README.md

@@ -1,66 +1,47 @@
 # Codex Auto Approve
 
-A small Codex plugin that can automatically allow supported permission
-requests. The switch is explicit, persistent, and **disabled by default**.
-
-> [!WARNING]
-> Enabling Auto Approve lets Codex proceed without asking you for every
-> supported permission request. Review the plugin and only enable it in an
-> environment you trust. Disable it as soon as you no longer need it.
+A Codex plugin that automatically allows supported permission requests when
+explicitly enabled. The switch is persistent and **disabled by default**.
 
 ## Requirements
 
-- A recent version of Codex with plugin and hook support
-- Node.js 22 or newer, with `node` on `PATH`
-
-## Install the Codex plugin
+- **Node.js 22 or newer**, with `node` on `PATH`.
+- A recent **Codex CLI with plugin and hook support**, with `codex` on `PATH`.
+- `npm` and `npx` on `PATH` for the npm commands below.
 
-Add this repository as a Codex plugin marketplace, then install the plugin:
+## Install
 
 ```sh
-codex plugin marketplace add fuliucansheng/codex-auto-approve
-codex plugin add auto-approve@codex-auto-approve
+npx codex-auto-approve@latest install
 ```
 
-The marketplace ships the prebuilt `scripts/auto_approve.js` controller inside
-the plugin. Installation needs only Node.js: no `npm install`, build step,
-`tsx`, or `ts-node` is needed. The plugin has no production dependencies, and
-its local `package.json` keeps the JavaScript runnable regardless of a parent
-package's module type.
+The one-command installer requires **version 0.2.0 or newer**. For older
+versions, use the manual alternative below. Installing the npm package alone
+does not register the plugin.
 
-Start a new Codex conversation after installation so the skill and hook are
-loaded. You can inspect the installed hook with `/hooks`.
+### Manual alternative
 
-## npm CLI
-
-Once the package is published to npm, install the command globally:
+These are the same two commands the installer runs; they require no npm
+installation or build step:
 
 ```sh
-npm install -g codex-auto-approve
-codex-auto-approve status
-codex-auto-approve enable
-codex-auto-approve disable
+codex plugin marketplace add fuliucansheng/codex-auto-approve
+codex plugin add auto-approve@codex-auto-approve
 ```
 
-Or run without a global installation:
-
-```sh
-npx --yes codex-auto-approve status
-npx --yes codex-auto-approve enable
-npx --yes codex-auto-approve disable
-```
+Both methods register a durable GitHub marketplace source, fetched from this
+repository's **`main` branch**, rather than a temporary npx cache path. The npm
+version selects the installer only: even a pinned npm version does not pin the
+plugin version or install the plugin from the npm tarball.
 
-Node.js 22 or newer is required. The npm package includes prebuilt JavaScript
-and has no production dependencies or consumer build step. Installing the CLI
-alone **does not register Codex hooks or skills**; use the marketplace
-installation above for integration with Codex. Both interfaces control the
-same local switch. The tarball also preserves the root
-`.agents/plugins/marketplace.json` descriptor and the complete
-`plugins/auto-approve` directory layout for marketplace use.
+Installation **does not enable automatic approval** or change the existing
+switch: a missing switch stays disabled, and an enabled switch stays enabled.
+Restart Codex and start a **new conversation**, then inspect the hook with
+`/hooks`.
 
 ## Use
 
-Invoke the bundled skill in Codex:
+In Codex, select the skill by typing `$` or through `/skills`:
 
 ```text
 $auto-approve status
@@ -68,181 +49,59 @@ $auto-approve enable
 $auto-approve disable
 ```
 
-Type `$` in the composer to select the skill, or find it through `/skills`.
-`$auto-approve` is a plugin skill mention, not a built-in slash command.
+`status` shows the current switch, `enable` allows all supported permission
+requests automatically, and `disable` restores the normal approval flow.
+`$auto-approve` is a plugin skill, not a built-in slash command.
 
-The actions are:
+You can also control the same switch from a terminal using the npm CLI:
 
-- `status`: show whether automatic approval is enabled.
-- `enable`: automatically allow all supported `PermissionRequest` events.
-- `disable`: return to the normal Codex approval flow.
-
-The skill runs the bundled Node.js controller. `status` exits with code 0 when
-enabled and 1 when disabled. Successful `enable` and `disable` actions exit 0;
-invalid arguments exit 2 and write usage to stderr. Filesystem errors during
-enable or disable exit 1 and write an error to stderr.
+```sh
+npx codex-auto-approve@latest status
+npx codex-auto-approve@latest enable
+npx codex-auto-approve@latest disable
+```
 
 ## Update
 
+Refresh the marketplace and reinstall the plugin:
+
 ```sh
 codex plugin marketplace upgrade codex-auto-approve
 codex plugin add auto-approve@codex-auto-approve
 ```
 
-Start a new Codex conversation after updating.
+Start a new Codex conversation after updating. Updating the npm CLI alone does
+not update the installed plugin.
 
 ## Uninstall
 
-Disable Auto Approve first, then remove the plugin and marketplace:
+Disable automatic approval in Codex first:
 
 ```text
 $auto-approve disable
 ```
 
+Then remove the plugin and marketplace in your terminal:
+
 ```sh
 codex plugin remove auto-approve@codex-auto-approve
 codex plugin marketplace remove codex-auto-approve
 ```
 
-## How it works
+## Safety
 
-The controller stores the enabled state at:
+While enabled, all supported permission requests are allowed without the normal
+confirmation prompt. Review the plugin, enable it only in an environment you
+trust, and disable it when finished.
 
-```text
-~/.local/state/codex-auto-approve/enabled.json
-```
-
-Only an object containing `"enabled": true` enables the bundled
-`PermissionRequest` hook, which returns an `allow` decision. Existing
-`enabled.json` files remain compatible. Missing, unreadable, malformed, or
-non-object state fails closed, as do other enabled values such as `"true"` or
-`1`. Invalid hook input silently does nothing. Status and hook calls never
-create or repair state; only an explicit enable action writes the switch.
-
-On filesystems supporting POSIX modes, newly created state directories use
-`0700` and the state file uses `0600`. Disable removes only `enabled.json` and
-is safe to repeat.
-
-The hook only covers permission requests exposed to Codex lifecycle hooks,
-including supported shell, file-edit, and MCP tool requests. Some Computer Use
-and app-level confirmations are always shown directly to the user and cannot
-be auto-approved by this plugin. Managed workspace policy can also limit what
-the plugin is allowed to approve.
-
-## Local development
-
-[src/auto_approve.ts](src/auto_approve.ts) is the canonical source. `tsc`
-compiles it to the checked-in
-[plugins/auto-approve/scripts/auto_approve.js](plugins/auto-approve/scripts/auto_approve.js).
-Include the regenerated JavaScript with every source change so marketplace
-copies remain ready to run. The root development dependencies are only the
-TypeScript compiler and Node type definitions.
-
-```sh
-npm ci
-npm run build
-npm run typecheck
-npm test
-git diff --check
-```
-
-Tests use Node's built-in test/assert modules and execute the compiled CLI in
-child processes, including a standalone copy of the plugin in a path with
-spaces. The test runner and every controller invocation use isolated temporary
-`HOME` and `USERPROFILE` directories. Build before testing source changes;
-`npm test` checks the shipped JavaScript and runs real `npm pack`, offline
-installation into a separate temporary global prefix, executable CLI and
-standalone plugin smoke tests, and credential-free `npm publish --dry-run`.
-Package tests check exact tarball contents, metadata, executable mode, version
-parity, and absence of source, developer scripts, and runtime dependencies.
-Only `prepack` rebuilds (`npm run build`); it never runs tests, avoiding recursion.
-Package tests use empty temporary npm configs and a separate cache as well as
-an isolated home. Release validator behavior tests cover matching versions,
-mismatches, malformed tags, and rejection of prereleases.
-
-CI runs these checks on Node.js 22 and 24 on Linux and macOS and rejects drift
-between the source and checked-in JavaScript. POSIX mode checks skip on
-Windows; permission-denial checks also skip when run as root.
-
-## npm releases
-
-Publishing requires a maintainer with permission to publish the npm package
-and manage this repository's GitHub Actions settings. Configure trusted
-publishing or the first-publication bootstrap described below before releasing.
-The npm installation commands above require a successful publication first.
-
-The [publish workflow](.github/workflows/publish-npm.yml) runs **only** when a
-GitHub release is published. It skips releases marked as prereleases and
-requires a stable, canonical `vX.Y.Z` tag. Prerelease versions and build metadata
-do not publish, even if the GitHub release is incorrectly marked stable. PRs
-and ordinary branch pushes never trigger npm publication.
-
-Keep these versions identical when preparing a release (currently `0.1.1`):
-
-- Root `package.json`
-- `package-lock.json`: top-level `version` and `packages[""].version`
-- `plugins/auto-approve/package.json`
-- `plugins/auto-approve/.codex-plugin/plugin.json`
-
-After updating the manifests, refresh the lockfile with
-`npm install --package-lock-only`, then run:
-
-```sh
-npm ci
-npm run build
-npm run typecheck
-npm test
-npm run validate:release -- v0.1.1
-git diff --exit-code -- plugins/auto-approve/scripts/auto_approve.js
-git diff --check
-```
-
-Use the intended version in the validation command for future releases.
-Include regenerated JavaScript with source changes. After reviewing and merging
-the release changes, tag that exact commit with the matching `vX.Y.Z` and
-publish a stable GitHub release for that tag. npm versions are immutable;
-fixes after publication require a new version and tag.
-
-The workflow checks out the exact release tag, verifies all version fields,
-installs dependencies, builds, typechecks, tests, and rejects generated artifact
-drift. Tests retain their installed and inspected archive using
-`NPM_TEST_PACK_DESTINATION`; the publish step sends that same tarball with
-`--access public --provenance`. Release publish jobs are serialized.
-
-### Trusted publishing and first-publication bootstrap
-
-Publishing uses a GitHub-hosted Ubuntu runner with Node.js 24 and explicitly
-pinned npm 11.6.2. npm trusted publishing requires npm **11.5.1 or newer** and
-Node.js **22.14.0 or newer**; this is separate from the CLI's Node.js 22 runtime
-minimum. The workflow grants only `contents: read` and `id-token: write`.
-
-Once the package exists, open its npm settings and add a **GitHub Actions**
-Trusted Publisher with these exact fields:
-
-| Field | Value |
-| --- | --- |
-| Organization or user | `fuliucansheng` |
-| Repository | `codex-auto-approve` |
-| Workflow filename | `publish-npm.yml` |
-| Environment | Leave blank (the workflow has no environment) |
-| Allowed actions (if shown) | Allow direct publishing with `npm publish` |
-
-No npm token is needed after that mapping is configured. The workflow uses npm
-OIDC automatically when `secrets.NPM_TOKEN` is absent. As recommended by the
-[npm trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/),
-the release workflow does not restore or save dependency caches.
-
-For the first publication, the package does not yet have settings for a trusted
-publisher. An authorized maintainer can create a short-lived granular npm token
-with permission to create/publish this package (and bypass 2FA for automation),
-then add it as the repository Actions secret **`NPM_TOKEN`**. The same workflow
-uses it only in the publish step as an optional bootstrap fallback. After the
-first successful stable release, configure the Trusted Publisher mapping,
-remove the repository secret, and revoke the bootstrap token. Subsequent
-releases use OIDC. Do not put tokens in repository files. These setup steps
-must be performed by a maintainer; a dry run verifies packaging, not registry
-authorization or successful publication.
+The switch is stored at `~/.local/state/codex-auto-approve/enabled.json`.
+Missing, unreadable, or invalid state leaves automatic approval disabled.
+The hook covers supported shell, file-edit, and MCP permission requests; some
+Computer Use and app-level confirmations still require user approval. Managed
+workspace policy can also limit what the plugin may approve.
 
 ## License
 
 [MIT](LICENSE)
+
+[Contributing](https://github.com/fuliucansheng/codex-auto-approve/blob/main/docs/MAINTAINING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-auto-approve",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/plugins/auto-approve/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-approve",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Explicitly toggle automatic approval for supported Codex permission requests.",
   "author": {
     "name": "fuliucansheng",

package/plugins/auto-approve/README.md

@@ -1,30 +1,40 @@
 # Auto Approve
 
-Auto Approve is a Codex plugin that automatically allows supported permission
-requests only while you have explicitly enabled it. It is disabled by default.
+A Codex plugin that automatically allows supported permission requests when
+explicitly enabled. The switch is persistent and **disabled by default**.
 
-## Requirements
+## Install
 
-- A recent version of Codex with plugin and hook support
-- Node.js 22 or newer, with `node` on `PATH`
+Requires **Node.js 22 or newer** and a recent **Codex CLI with plugin and hook
+support**, with `node` and `codex` on `PATH`. For one-command installation,
+`npm` and `npx` must also be on `PATH`:
 
-## Install
+```sh
+npx codex-auto-approve@latest install
+```
+
+The installer requires **version 0.2.0 or newer**. For older versions, use
+these manual commands:
 
 ```sh
 codex plugin marketplace add fuliucansheng/codex-auto-approve
 codex plugin add auto-approve@codex-auto-approve
 ```
 
-The plugin includes the prebuilt `scripts/auto_approve.js` controller and has
-no production dependencies. Marketplace installations run directly with
-Node.js; no `npm install`, build step, `tsx`, or `ts-node` is needed. Keep the
-entire plugin directory, including its local `package.json`, so it also works
-under a parent package configured as an ES module.
+The manual alternative needs no npm installation or build step. Installing the
+npm package alone does not register the plugin. Both methods use the durable
+GitHub marketplace on **`main`**, not an npx cache path. The npm version selects
+only the installer; pinning it does not pin the plugin version or install the
+plugin from the npm tarball.
+
+Installation **does not enable automatic approval** or change the existing
+switch: a missing switch stays disabled, and an enabled switch stays enabled.
+Restart Codex and start a **new conversation**, then inspect the hook with
+`/hooks`.
 
-Start a new Codex conversation after installation and inspect the bundled
-`PermissionRequest` hook with `/hooks`.
+## Use
 
-## Use inside Codex
+In Codex, select the skill by typing `$` or through `/skills`:
 
 ```text
 $auto-approve status
@@ -32,32 +42,37 @@ $auto-approve enable
 $auto-approve disable
 ```
 
-Type `$` to select the skill, or select it through `/skills`. This is a plugin
-skill rather than a new built-in slash command.
+`status` shows the current switch, `enable` allows supported requests
+automatically, and `disable` restores the normal approval flow. This is a
+plugin skill, not a built-in slash command. For terminal controls, see the
+[root README](https://github.com/fuliucansheng/codex-auto-approve#use).
 
-> [!WARNING]
-> While enabled, all supported permission requests are allowed without the
-> normal confirmation prompt. Only enable it in an environment you trust.
+## Update and uninstall
 
-The hook covers permission requests exposed to Codex lifecycle hooks,
-including supported shell, file-edit, and MCP tool requests. Some Computer Use
-and app-level confirmations cannot be auto-approved by this plugin.
+To update, run these commands and start a new Codex conversation:
+
+```sh
+codex plugin marketplace upgrade codex-auto-approve
+codex plugin add auto-approve@codex-auto-approve
+```
+
+Updating the npm CLI alone does not update the installed plugin.
+
+To uninstall, run `$auto-approve disable` in Codex first, then in your terminal:
+
+```sh
+codex plugin remove auto-approve@codex-auto-approve
+codex plugin marketplace remove codex-auto-approve
+```
 
-The switch remains at `~/.local/state/codex-auto-approve/enabled.json` and is
-compatible with existing state files. Only the boolean `true` in an object's
-`enabled` field enables approval. Missing, unreadable, malformed, or non-object
-state fails closed; malformed or non-object hook input silently does nothing.
-Only explicit enable writes state, and disable is safe to repeat. On POSIX
-filesystems, new state directories use `0700` and the file uses `0600`.
+## Safety
 
-`status` exits 0 when enabled and 1 when disabled. Successful enable/disable
-actions exit 0, filesystem write failures exit 1, and invalid arguments exit 2.
+While enabled, all supported permission requests are allowed without the normal
+confirmation prompt. Enable only in an environment you trust and disable when
+finished. Some Computer Use and app-level confirmations still require user
+approval, and managed workspace policy may limit what the plugin can approve.
 
-## Development
+The switch is stored at `~/.local/state/codex-auto-approve/enabled.json`.
+Missing, unreadable, or invalid state leaves automatic approval disabled.
 
-In a repository clone, edit `src/auto_approve.ts`, then run `npm ci`,
-`npm run build`, `npm run typecheck`, and `npm test` from the repository root.
-Include the regenerated `plugins/auto-approve/scripts/auto_approve.js` with
-source changes. Tests execute the compiled controller with isolated temporary
-`HOME` and `USERPROFILE` directories. CI checks Node.js 22/24 on Linux/macOS
-and verifies that the checked-in JavaScript matches the TypeScript source.
+[Contributing](https://github.com/fuliucansheng/codex-auto-approve/blob/main/docs/MAINTAINING.md)

package/plugins/auto-approve/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-auto-approve",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": true,
   "type": "commonjs",
   "engines": {

package/plugins/auto-approve/scripts/auto_approve.js

@@ -2,6 +2,7 @@
 "use strict";
 // Source: src/auto_approve.ts. Rebuild with npm run build; do not edit the JS.
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -47,6 +48,33 @@ function status() {
     console.log(`Auto Approve: ${enabled ? 'enabled' : 'disabled'}`);
     return enabled ? 0 : 1;
 }
+function install() {
+    // Keep the marketplace source durable; an npx cache path can disappear.
+    const commands = [
+        ['plugin', 'marketplace', 'add', 'fuliucansheng/codex-auto-approve'],
+        ['plugin', 'add', 'auto-approve@codex-auto-approve'],
+    ];
+    for (const args of commands) {
+        const result = (0, node_child_process_1.spawnSync)('codex', args, { stdio: 'inherit' });
+        if (result.error) {
+            if ('code' in result.error && result.error.code === 'ENOENT') {
+                throw new Error('codex executable not found. Install the Codex CLI with plugin support and ensure codex is on PATH, then retry.');
+            }
+            throw result.error;
+        }
+        if (result.signal) {
+            throw new Error(`codex ${args.join(' ')} terminated by signal ${result.signal}`);
+        }
+        if (result.status === null) {
+            throw new Error(`codex ${args.join(' ')} exited without a status`);
+        }
+        if (result.status !== 0)
+            return result.status;
+    }
+    console.log('Auto Approve: plugin installed. Automatic approval state is unchanged.');
+    console.log('Restart Codex and start a new conversation to load the plugin.');
+    return 0;
+}
 function runHook() {
     const event = readObject(0);
     if (event?.hook_event_name !== 'PermissionRequest' || !isEnabled()) {
@@ -66,7 +94,7 @@ function runHook() {
     return 0;
 }
 function usage() {
-    console.error('Usage: auto_approve.js {enable|disable|status}');
+    console.error('Usage: codex-auto-approve {install|enable|disable|status}');
     return 2;
 }
 function main() {
@@ -75,6 +103,8 @@ function main() {
     const command = process.argv[2];
     try {
         switch (command) {
+            case 'install':
+                return install();
             case 'enable':
                 enable();
                 return 0;