@michaelschnyder/teams-cli 0.1.0

package/dist/update.js

@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME } from "./version.js";
+export const UPDATE_INTERVAL_MS = 60 * 60 * 1000;
+const UPDATE_TIMEOUT_MS = 3_000;
+export function updateStateFile(storageRoot = join(homedir(), ".teams-cli")) {
+    return join(storageRoot, "update-check.json");
+}
+export function updateChecksDisabled(environment = process.env) {
+    const enabled = (value) => value === "1" || value?.toLowerCase() === "true";
+    return enabled(environment.NO_UPDATE_NOTIFIER) || enabled(environment.TEAMS_CLI_DISABLE_UPDATE_CHECK) ||
+        enabled(environment.CI) || enabled(environment.TEAMS_CLI_UPDATE_WORKER);
+}
+export async function loadUpdateState(file = updateStateFile()) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const candidate = parsed;
+        if (candidate.version !== 1 || typeof candidate.checkedAt !== "string")
+            return null;
+        if (candidate.latestVersion !== undefined && typeof candidate.latestVersion !== "string")
+            return null;
+        if (candidate.pendingVersion !== undefined && typeof candidate.pendingVersion !== "string")
+            return null;
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveUpdateState(state, file) {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await chmod(dirname(file), 0o700);
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+}
+export function parseVersion(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
+    if (!match)
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] ?? null,
+    };
+}
+export function isNewerVersion(current, candidate) {
+    const left = parseVersion(current);
+    const right = parseVersion(candidate);
+    if (!left || !right)
+        return false;
+    if (right.prerelease && !left.prerelease)
+        return false;
+    for (let index = 0; index < left.core.length; index += 1) {
+        const currentPart = left.core[index] ?? 0;
+        const candidatePart = right.core[index] ?? 0;
+        if (candidatePart !== currentPart)
+            return candidatePart > currentPart;
+    }
+    if (left.prerelease && !right.prerelease)
+        return true;
+    return Boolean(left.prerelease && right.prerelease && right.prerelease !== left.prerelease &&
+        right.prerelease.localeCompare(left.prerelease, undefined, { numeric: true }) > 0);
+}
+export async function runUpdateWorker(currentVersion, file = updateStateFile(), fetcher = fetch, now = new Date()) {
+    const previous = await loadUpdateState(file);
+    const next = {
+        version: 1,
+        checkedAt: now.toISOString(),
+        ...(previous?.latestVersion ? { latestVersion: previous.latestVersion } : {}),
+        ...(previous?.pendingVersion ? { pendingVersion: previous.pendingVersion } : {}),
+    };
+    try {
+        const encodedName = PACKAGE_NAME.replace("/", "%2F");
+        const response = await fetcher(`https://registry.npmjs.org/${encodedName}/latest`, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw new Error(`npm registry returned ${response.status}`);
+        const payload = await response.json();
+        const latest = payload && typeof payload === "object" ? payload.version : undefined;
+        if (typeof latest !== "string")
+            throw new Error("npm registry returned no version");
+        next.latestVersion = latest;
+        if (isNewerVersion(currentVersion, latest))
+            next.pendingVersion = latest;
+        else
+            delete next.pendingVersion;
+    }
+    catch {
+        // Update checks are advisory and must never make a CLI command fail.
+    }
+    await saveUpdateState(next, file);
+}
+export async function prepareUpdateNotification(options) {
+    const environment = options.environment ?? process.env;
+    if (updateChecksDisabled(environment))
+        return;
+    const file = options.stateFile ?? updateStateFile();
+    const state = await loadUpdateState(file);
+    if (state?.pendingVersion && isNewerVersion(options.currentVersion, state.pendingVersion)) {
+        (options.stderr ?? process.stderr).write(`A new teams-cli version is available: ${options.currentVersion} → ${state.pendingVersion}. ` +
+            "Run `teams-cli version --upgrade`.\n");
+        const consumed = { ...state };
+        delete consumed.pendingVersion;
+        try {
+            await saveUpdateState(consumed, file);
+        }
+        catch {
+            // A read-only or damaged cache must not prevent the requested CLI command.
+        }
+    }
+    const now = options.now ?? new Date();
+    const checkedAt = state ? Date.parse(state.checkedAt) : Number.NaN;
+    if (Number.isFinite(checkedAt) && now.getTime() - checkedAt < UPDATE_INTERVAL_MS)
+        return;
+    if (options.spawnWorker) {
+        options.spawnWorker(file);
+        return;
+    }
+    const entrypoint = fileURLToPath(new URL("./cli.js", import.meta.url));
+    const child = spawn(process.execPath, [entrypoint, "--internal-update-check", options.currentVersion, file], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: { ...environment, TEAMS_CLI_UPDATE_WORKER: "1" },
+    });
+    child.on("error", () => undefined);
+    child.unref();
+}

package/dist/upgrade.js

@@ -0,0 +1,45 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, win32 } from "node:path";
+import { promisify } from "node:util";
+import { PACKAGE_NAME } from "./version.js";
+const execFileAsync = promisify(execFile);
+export function npmInvocation(platform = process.platform, nodeExecutable = process.execPath, npmExecPath = process.env.npm_execpath) {
+    if (npmExecPath)
+        return { command: nodeExecutable, args: [npmExecPath] };
+    if (platform === "win32") {
+        return {
+            command: nodeExecutable,
+            args: [win32.join(win32.dirname(nodeExecutable), "node_modules", "npm", "bin", "npm-cli.js")],
+        };
+    }
+    return { command: "npm", args: [] };
+}
+const defaultRunner = (command, args) => new Promise((resolve, reject) => {
+    const child = spawn(command, [...args], { stdio: "inherit", shell: false, windowsHide: true });
+    child.once("error", reject);
+    child.once("exit", (code) => resolve(code ?? 1));
+});
+export async function upgradeCli(options = {}) {
+    const runner = options.runner ?? defaultRunner;
+    const npm = npmInvocation();
+    const installStatus = await runner(npm.command, [...npm.args, "install", "--global", `${PACKAGE_NAME}@latest`]);
+    if (installStatus !== 0) {
+        throw new Error(`npm upgrade failed with exit code ${installStatus}`);
+    }
+    const globalRoot = options.globalRoot ?? (async () => {
+        const { stdout } = await execFileAsync(npm.command, [...npm.args, "root", "--global"], {
+            encoding: "utf8",
+            windowsHide: true,
+        });
+        return stdout.trim();
+    });
+    const installedCli = join(await globalRoot(), ...PACKAGE_NAME.split("/"), "dist", "cli.js");
+    if (!existsSync(installedCli) && !options.globalRoot) {
+        throw new Error(`The updated CLI was not found at ${installedCli}`);
+    }
+    const reinstallStatus = await runner(process.execPath, [installedCli, "skills", "reinstall"]);
+    if (reinstallStatus !== 0) {
+        throw new Error(`The CLI was upgraded, but skill reinstallation failed with exit code ${reinstallStatus}`);
+    }
+}

package/dist/version.js

@@ -0,0 +1,7 @@
+import { createRequire } from "node:module";
+const metadata = createRequire(import.meta.url)("../package.json");
+if (typeof metadata.name !== "string" || typeof metadata.version !== "string") {
+    throw new Error("Installed package metadata is invalid");
+}
+export const PACKAGE_NAME = metadata.name;
+export const CLI_VERSION = metadata.version;

package/dist/yaml.js

@@ -0,0 +1,33 @@
+import { parseDocument } from "yaml";
+export function parseStrictYaml(raw, label) {
+    const document = parseDocument(raw, {
+        version: "1.2",
+        uniqueKeys: true,
+        merge: false,
+        prettyErrors: true,
+    });
+    if (document.errors.length > 0) {
+        throw new Error(`${label} is invalid YAML: ${document.errors[0]?.message ?? "unknown error"}`);
+    }
+    if (document.warnings.length > 0) {
+        throw new Error(`${label} uses unsupported YAML: ${document.warnings[0]?.message ?? "unknown warning"}`);
+    }
+    try {
+        return document.toJS({ maxAliasCount: 0 });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label} uses unsupported YAML: ${detail}`);
+    }
+}
+export function requireObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return value;
+}
+export function rejectUnknownKeys(object, allowed, label) {
+    const unknown = Object.keys(object).find((key) => !allowed.includes(key));
+    if (unknown)
+        throw new Error(`${label} contains unknown field ${unknown}`);
+}

package/docs/releasing.md

@@ -0,0 +1,48 @@
+# Releasing
+
+Releases are published from GitHub Releases by `.github/workflows/publish-npm.yml`. The release tag must exactly equal `v` followed by the version in `package.json`.
+
+## Repository setup
+
+Before the first release:
+
+1. Make the repository public so npm provenance can reference it.
+2. Protect `main` and require the CI and CodeQL checks.
+3. Enable secret scanning and push protection.
+4. Create a GitHub environment named `npm`, restrict it to release tags, and add a required reviewer.
+5. Enable two-factor authentication on the npm maintainer account.
+
+## First publication
+
+npm cannot configure a trusted publisher until the package exists. Bootstrap `0.1.0` once:
+
+1. Create a short-lived granular npm token that can create the public package in the `@michaelschnyder` scope and can bypass publish 2FA for this one automated run.
+2. Add it to the protected `npm` environment as `NPM_BOOTSTRAP_TOKEN`.
+3. Confirm `npm run check`, `npm test`, `npm run build`, `npm run package:check`, and `npm run package:smoke` pass on a clean checkout.
+4. Create and publish the GitHub Release `v0.1.0`.
+5. Confirm the workflow and npm provenance succeed.
+
+Immediately afterward, delete the GitHub secret and revoke the npm token.
+
+## Configure trusted publishing
+
+On npm, configure the package's trusted publisher with:
+
+- Provider: GitHub Actions
+- Organization or user: `michaelschnyder`
+- Repository: `teams-cli`
+- Workflow: `publish-npm.yml`
+- Environment: `npm`
+- Allowed action: publish
+
+Set package publishing access to require 2FA and disallow tokens. Later workflow runs authenticate with short-lived OIDC credentials and generate provenance automatically.
+
+## Subsequent releases
+
+1. Update `package.json` and `package-lock.json` to the same semantic version.
+2. Update this changelog and packaged skill metadata.
+3. Merge the release changes through protected `main`.
+4. Create and publish a GitHub Release with the exact matching `vX.Y.Z` tag.
+5. Verify the workflow, npm package contents, provenance, executable version, and `latest` distribution tag.
+
+Published npm versions are immutable. If a release is defective, fix it in a new version rather than attempting to reuse or overwrite the published version.

package/docs/use/authentication.md

@@ -0,0 +1,25 @@
+# Authentication
+
+Login uses a dedicated Edge or Chrome profile and stores the resulting Teams tokens under the verified tenant and user identity.
+
+```bash
+teams-cli --tenant TENANT_ID auth login
+teams-cli --profile test-alice auth login
+teams-cli --profile personal auth whoami
+teams-cli --profile personal auth refresh
+teams-cli --profile personal auth logout
+```
+
+`--user USER_ID` constrains login to the expected Microsoft object ID. The CLI rejects tokens for another tenant or user. The stable session identity is the pair `(tenantId, userId)`; usernames are mutable login hints.
+
+Tokens for different users never share a session file. Browser state is also isolated by tenant, user, and browser. Selecting another browser does not invalidate existing tokens, but that browser needs its own authenticated state when browser-backed token acquisition is required.
+
+Raw bearer tokens remain available:
+
+```bash
+teams-cli --profile personal auth tokens
+teams-cli --profile personal auth token access
+teams-cli --profile personal auth tokens --decode
+```
+
+If an active subject policy applies, raw bearer output requires `rawTokenExport: true` in every applicable active policy. Decoded JWT claims remain available. Treat exported tokens like passwords; another HTTP client can use them to bypass cooperative CLI policy checks.

package/docs/use/policies.md

@@ -0,0 +1,136 @@
+# Policies
+
+Policies are optional named YAML files under `~/.teams-cli/policies/`. They limit the effective identity, message destinations, and raw-token export for matching subject paths.
+
+## How policy selection works
+
+The current subject is the canonical absolute path from which the CLI is invoked. This path selector is a convention of this CLI, not an external standard or a strong security identity. Symlinks are resolved before matching.
+
+Each policy contains one or more absolute path patterns. Patterns use Node.js glob syntax:
+
+```yaml
+subject:
+  paths:
+    - /Users/me/Workspaces/project
+    - /Users/me/Workspaces/client-*/**
+```
+
+The paths within one policy are alternatives: matching any one makes that policy applicable. Several policies may apply to the same subject. Every active policy must allow an operation, so adding another active policy can only preserve or narrow access.
+
+The CLI validates every `.yaml` file in the policy directory before matching. An unreadable, malformed, misnamed, unsupported, or dangerously writable active policy puts authenticated operations into fail-safe mode across every subject. Files without a `.yaml` extension are not policies and are ignored.
+
+## Inactive and active policies
+
+New policies are inactive. An inactive policy runs in audit mode:
+
+- The CLI warns on stderr that the policy is not enforcing restrictions.
+- The policy is still evaluated.
+- The CLI warns when it would deny the selected identity or operation.
+- The operation remains allowed unless another applicable active policy denies it.
+
+An active policy enforces its identity and allowlists. Active policies cannot be deactivated through the CLI. This makes activation deliberate without claiming that the file itself is locked.
+
+## Create and refine a policy
+
+Create a named restrictive policy for the current path. Without explicit subjects, initialization adds both the current canonical path and a descendant glob so commands from its subdirectories remain covered:
+
+```bash
+teams-cli --profile personal policy init project-agent
+```
+
+Supply several subject patterns by repeating `--subject`:
+
+```bash
+teams-cli --profile personal policy init client-projects \
+  --subject '/Users/me/Workspaces/client-a/**' \
+  --subject '/Users/me/Workspaces/client-b/**'
+```
+
+Subject patterns must be absolute. Quote patterns so the shell does not expand them before the CLI receives them.
+
+The generated policy is restrictive and inactive:
+
+```yaml
+version: 1
+name: project-agent
+active: false
+subject:
+  paths:
+    - /Users/me/Workspaces/project
+    - /Users/me/Workspaces/project/**
+identity:
+  tenantId: tenant-id
+  userId: user-id
+allow:
+  messageSend:
+    chats: []
+    channels: []
+  rawTokenExport: false
+```
+
+Edit the file outside the CLI and add only the exact, case-sensitive chat and channel IDs required by the subject. A chat entry never permits a channel with the same text. Set `rawTokenExport: true` only when complete bearer tokens are genuinely required; decoded claims do not need that permission.
+
+Inspect configured or applicable policies:
+
+```bash
+teams-cli policy list
+teams-cli policy show project-agent
+teams-cli policy show
+teams-cli policy show --path /absolute/path/to/check
+```
+
+Check representative decisions while the policy is still inactive. Warnings show what audit mode would deny:
+
+```bash
+teams-cli --profile personal policy check send --chat CHAT_ID
+teams-cli --profile personal policy check send --channel CHANNEL_ID
+teams-cli --profile personal policy check raw-tokens
+```
+
+## Activate and protect a policy
+
+Activate enforcement by name:
+
+```bash
+teams-cli policy activate project-agent
+```
+
+On POSIX systems, the command prints an exact additional protection instruction such as:
+
+```bash
+chmod 400 -- '/Users/me/.teams-cli/policies/project-agent.yaml'
+```
+
+Activation and filesystem protection are separate:
+
+- `active: true` makes the CLI enforce the policy.
+- Owner-read-only permissions reduce accidental same-user modification.
+- An active owner-writable policy is enforced but produces a warning.
+- An active policy or policy directory writable by group or other users fails closed.
+- On Windows, use an administrator-managed read-only ACL instead.
+
+Read-only permissions are defense in depth, not an immutable lock. A process with sufficient owner or administrator privileges can still replace the file or use exported tokens outside this CLI.
+
+## Deactivate, revise, or remove a policy
+
+The CLI intentionally has no deactivate, edit, or remove command. Use `policy show NAME` to obtain the exact file path. If the store is malformed, the error identifies the offending file.
+
+On POSIX systems, make that one file writable before changing it:
+
+```bash
+chmod u+w '/exact/policy/path.yaml'
+```
+
+To return to audit mode, set `active: false`. To revise an active policy, deactivate it first, make the changes, use `policy check`, and activate it again. To remove it completely, delete only that exact file:
+
+```bash
+rm '/exact/policy/path.yaml'
+```
+
+Removing the last applicable active policy may make the subject unrestricted. Confirm the result with `policy show` and `policy check`.
+
+If permissions are controlled by a read-only mount, sandbox, separate OS identity, or administrator ACL, revise the policy at that external enforcement layer.
+
+## Security boundary
+
+Policies primarily prevent accidental messages to the wrong destinations. Strong, non-bypassable enforcement requires controls outside the agent process, such as a separate OS identity, read-only container mount, restricted network egress, or server-side Teams permissions.

package/docs/use/profiles.md

@@ -0,0 +1,57 @@
+# Profiles
+
+Profiles are named configuration baselines similar to AWS CLI profiles. They do not own tokens and are not security boundaries.
+
+Profiles are stored in `~/.teams-cli/config.yaml`. For example:
+
+```yaml
+version: 1
+profiles:
+  default:
+    tenantId: personal-tenant-id
+    userId: personal-user-id
+    username: me@example.test
+    browser: edge
+  test-alice:
+    tenantId: test-tenant-id
+    userId: alice-user-id
+    username: alice@example.test
+    browser: chrome
+```
+
+When neither `--profile` nor `TEAMS_CLI_PROFILE` is provided, the CLI selects the profile named `default` if it exists:
+
+```bash
+teams-cli auth whoami
+teams-cli message list --chat CHAT_ID
+```
+
+Select another profile explicitly without changing the default:
+
+```bash
+teams-cli --profile test-alice auth whoami
+```
+
+```bash
+teams-cli profile list
+teams-cli profile show personal
+teams-cli --tenant TENANT_ID --user USER_ID --browser chrome profile save personal
+teams-cli profile remove personal
+```
+
+Login creates or updates the selected profile with the verified tenant, user, username, and browser:
+
+```bash
+teams-cli --profile test-alice --tenant TENANT_ID auth login
+```
+
+Selection and precedence are:
+
+1. Global command options.
+2. `TEAMS_CLI_PROFILE`, `TEAMS_CLI_TENANT`, `TEAMS_CLI_USER`, and `TEAMS_CLI_BROWSER`.
+3. The selected profile, or the profile named `default` when none is selected.
+4. Built-in defaults such as Edge.
+
+The `default` profile is a selection fallback, not a source of field-by-field inheritance. A named profile does not inherit missing tenant, user, username, or browser fields from `default`; this prevents fields from two identities being combined accidentally. Several profiles may refer to the same tenant/user session. Removing a profile does not remove tokens; use `auth logout` with the corresponding identity for that.
+
+Policies are evaluated after all profile, environment, and flag overrides. Flags can override profile values but cannot weaken an applicable active policy.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@michaelschnyder/teams-cli",
+  "version": "0.1.0",
+  "description": "A safety-conscious CLI for persistent Microsoft Teams sessions",
+  "type": "module",
+  "bin": {
+    "teams-cli": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs/use",
+    "docs/releasing.md",
+    "README.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc && node scripts/copy-skills.mjs && node scripts/sync-skill-versions.mjs && node scripts/make-executable.mjs",
+    "check": "tsc --noEmit",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "test:e2e": "node --import tsx --test test/e2e/*.e2e.ts",
+    "test:live": "npm run test:e2e",
+    "prepack": "npm run build",
+    "package:check": "node scripts/check-package.mjs",
+    "package:smoke": "node scripts/smoke-package.mjs"
+  },
+  "keywords": [
+    "microsoft-teams",
+    "teams",
+    "cli",
+    "automation",
+    "agent-skills"
+  ],
+  "author": "Michael Schnyder",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/michaelschnyder/teams-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/michaelschnyder/teams-cli/issues"
+  },
+  "homepage": "https://github.com/michaelschnyder/teams-cli#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "playwright-core": "^1.54.2",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=22.20.0"
+  }
+}