potlot 0.0.0-stage → 0.1.6

package/LICENSE

@@ -0,0 +1,46 @@
+Potlot Freeware License
+
+Copyright (c) 2026 Heru Prasetyo. All rights reserved.
+
+Potlot (the "Software") is proprietary software distributed free of charge.
+By installing or using it you agree to these terms.
+
+1. Grant. You may download, install and use the Software, free of charge, on
+   any number of devices, for personal or commercial work.
+
+2. Your work. Designs, documents and other output you create with the
+   Software belong to you. The author claims no rights in them.
+
+3. Restrictions. Except where these terms or applicable law expressly allow
+   it, you may not:
+   a. sell, rent, lease, sublicense or otherwise charge for the Software;
+   b. redistribute the Software, modified or unmodified; share the official
+      download page instead;
+   c. modify, decompile, disassemble or reverse engineer the Software, or
+      create derivative works from it;
+   d. remove or alter any copyright, license or trademark notice in it.
+
+4. Third-party components. The Software includes open-source components
+   listed in THIRD_PARTY_NOTICES.txt. Each is licensed under its own terms,
+   and nothing in this license limits the rights those terms grant you.
+
+5. Third-party services. Features that use external services (AI providers,
+   agent CLIs, image or stock-photo APIs) run with your own accounts and keys.
+   Your use of those services, and any costs they charge, are governed by
+   their own terms.
+
+6. Updates and future licensing. The author may release later versions of
+   the Software under different terms, including an open-source license.
+   Those terms apply only to the versions released under them.
+
+7. Termination. Your rights under this license end automatically if you
+   breach it. You must then stop using and delete the Software.
+
+8. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+9. Limitation of liability. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+   OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+   THE USE OR OTHER DEALINGS IN THE SOFTWARE, INCLUDING LOSS OF DATA.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# potlot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Potlot command line. Its `potlot mcp` is an MCP server that lets Claude
+Code, Codex and other agents read and design Potlot documents (`.ptl`).
+
+## Use it from an agent
+
+Claude Code:
+
+```sh
+claude mcp add potlot -- npx -y potlot mcp
+```
+
+Any MCP client that starts stdio servers:
+
+```json
+{ "mcpServers": { "potlot": { "command": "npx", "args": ["-y", "potlot", "mcp"] } } }
+```
+
+## With and without the app
+
+When the Potlot app is installed, `potlot` runs the binary inside the app, so
+the MCP server and the app's engine are always the same version. When the
+app is running, the agent's edits go through it and show up live. When it is
+not, the engine runs inside the MCP server, and hands its documents over to
+the app as soon as the app starts.
+
+To watch the agent work, add `--open-app` (`npx -y potlot mcp --open-app`, or
+set `POTLOT_OPEN_APP=1`): the server starts the app if it is not running and
+shows each document the agent opens. It starts the app once; if you quit it,
+work carries on headless.
+
+Two engines never write to one document: a document open in one Potlot
+process waits a few seconds for the other to let go, then fails with a
+message naming that process.
+
+`potlot --which` prints the binary in use. `POTLOT_BIN=/path/to/potlot`
+picks another one.
+
+Binaries for macOS (Apple Silicon, Intel), Linux (x64, arm64) and Windows
+(x64). Linux and Windows are not tested yet.
+
+https://potlot.anaknegeri.dev

package/bin/potlot.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+'use strict'
+// Runs the potlot command line, e.g. `potlot mcp`, the MCP server for agents
+// such as Claude Code and Codex. `potlot --which` prints the binary used.
+const { spawn } = require('node:child_process')
+const fs = require('node:fs')
+const { PLATFORMS, packageName, resolveBinary } = require('../lib/resolve.js')
+
+const found = resolveBinary()
+if (!found) {
+  const here = `${process.platform}-${process.arch}`
+  console.error(
+    PLATFORMS.includes(here)
+      ? `potlot: ${packageName(process.platform, process.arch)} is not installed. Reinstall without --no-optional, or install the Potlot app.`
+      : `potlot: no Potlot binary for ${here}. Supported: ${PLATFORMS.join(', ')}.`,
+  )
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+if (args[0] === '--which') {
+  console.log(`${found.path} (${found.source})`)
+  process.exit(0)
+}
+
+if (found.source === 'package' && process.platform !== 'win32') {
+  // Some package managers drop the executable bit when unpacking.
+  try {
+    fs.accessSync(found.path, fs.constants.X_OK)
+  } catch {
+    try {
+      fs.chmodSync(found.path, 0o755)
+    } catch {}
+  }
+}
+
+const child = spawn(found.path, args, { stdio: 'inherit', windowsHide: true })
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => child.kill(signal))
+}
+child.on('error', (err) => {
+  console.error(`potlot: could not start ${found.path}: ${err.message}`)
+  process.exit(1)
+})
+child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 1)))

package/lib/resolve.js

@@ -0,0 +1,49 @@
+'use strict'
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+// Platforms with a binary package, as process.platform-process.arch.
+const PLATFORMS = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64', 'win32-x64']
+
+// The potlot binary the Potlot app ships, where its installers put it. Using
+// it keeps `potlot mcp` the same version as the app's daemon.
+function appBinaries(platform, env, home) {
+  if (platform === 'darwin') {
+    const inApp = path.posix.join('Potlot.app', 'Contents', 'MacOS', 'potlot-daemon')
+    return [path.posix.join('/Applications', inApp), path.posix.join(home, 'Applications', inApp)]
+  }
+  if (platform === 'win32' && env.LOCALAPPDATA) return [path.win32.join(env.LOCALAPPDATA, 'Potlot', 'potlot-daemon.exe')]
+  return []
+}
+
+function packageName(platform, arch) {
+  return `@potlot/${platform}-${arch}`
+}
+
+/**
+ * Picks the potlot binary to run: POTLOT_BIN, else the installed app's,
+ * else the one from this platform's package. Returns { path, source } or
+ * null when there is none.
+ */
+function resolveBinary({
+  platform = process.platform,
+  arch = process.arch,
+  env = process.env,
+  home = os.homedir(),
+  exists = (p) => fs.existsSync(p),
+  resolvePackage = (p) => require.resolve(p),
+} = {}) {
+  if (env.POTLOT_BIN) return { path: env.POTLOT_BIN, source: 'POTLOT_BIN' }
+  for (const p of appBinaries(platform, env, home)) {
+    if (exists(p)) return { path: p, source: 'app' }
+  }
+  const exe = platform === 'win32' ? 'potlot.exe' : 'potlot'
+  try {
+    return { path: resolvePackage(`${packageName(platform, arch)}/bin/${exe}`), source: 'package' }
+  } catch {
+    return null
+  }
+}
+
+module.exports = { PLATFORMS, appBinaries, packageName, resolveBinary }

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "potlot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "Potlot command line and MCP server: let Claude Code, Codex and other agents design in Potlot documents",
+  "homepage": "https://potlot.anaknegeri.dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "potlot": "bin/potlot.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@potlot/darwin-arm64": "0.1.6",
+    "@potlot/darwin-x64": "0.1.6",
+    "@potlot/linux-arm64": "0.1.6",
+    "@potlot/linux-x64": "0.1.6",
+    "@potlot/win32-x64": "0.1.6"
+  }
+}