@openagt/skill-scheduler 0.0.0-stage → 0.1.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: scheduler
+description: "Start and stop the project's scheduler, switch the commands it starts on a schedule on or off, set their pace, or start one now, when the person asks you to."
+---
+
+# Scheduler
+
+The scheduler starts agents on a schedule: the project's skills say which commands can run on one, and each machine switches them on for itself. It runs in its own process and needs no dashboard.
+
+Run the `scheduler` command at the project's root, always by its full name: `npx @openagt/skill-scheduler@0.1`. It prints one JSON document; a refusal exits 1 with why on stderr; a wrong command line exits 2 with the usage.
+
+Change it only when the person asks: every run it starts spends their quota.
+
+```
+npx @openagt/skill-scheduler@0.1 status                  on, running, the switches, and schedule: every command
+                                                          that can run on a schedule, with its pace (every), its check (when)
+npx @openagt/skill-scheduler@0.1 start                   the scheduler on, ticking every minute in its own process
+npx @openagt/skill-scheduler@0.1 stop                    the scheduler off; runs in flight go to their end
+npx @openagt/skill-scheduler@0.1 switch <command> on|off whether a command runs on this machine; every one starts off
+npx @openagt/skill-scheduler@0.1 pace <command> <N<m|h|d|w|mo>|work|skill> [HH:MM]
+                                                          how often at most it starts; work: whenever its check finds work;
+                                                          skill: its skill's own pace again
+npx @openagt/skill-scheduler@0.1 now <command>           one run of it now, whatever its switch and pace
+```
+
+A command is named as `status` names it, quoted when it has a word after it. A switched-on command starts nothing while the scheduler is off: switch it on, then `start`.
+
+The rest, such as a command's agent, model, publish level, or the person's own automations, is in its usage: `npx @openagt/skill-scheduler@0.1` with no command prints it.

package/bin/scheduler

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli.js'
+
+runCli(process.argv.slice(2), { cwd: process.cwd(), stdout: line => console.log(line), stderr: line => console.error(line) })
+  .then(code => {
+    process.exitCode = code
+  })
+  .catch(err => {
+    console.error(err)
+    process.exitCode = 1
+  })

package/dist/automation-file.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The file of a person's own automation, written and read back. Shared with the project it is a
+ * command skill's file (`.claude/skills/<name>/SKILL.md`); kept on this machine alone it is the
+ * same text in the tool's own folder (`.scheduler/automations/<name>.md`). The front matter
+ * makes it a command (`disable-model-invocation`) and carries the `schedule` the person picked;
+ * the text after it is the prompt.
+ *
+ * The tool rewrites and removes a file only while the file reads as the tool writes one: rewriting
+ * it then loses nothing a person wrote, and no skill a person or a package wrote is taken for an
+ * automation.
+ */
+/** An automation as a person fills it in. */
+export interface NewAutomation {
+    /** The command's name, without its slash: the skill's folder. */
+    name: string;
+    /** What the agent is told: the skill's whole text. */
+    prompt: string;
+    /** How often at most, as a skill writes it (`15m`, `1d`). */
+    every?: string;
+    /** The check, a shell line. */
+    when?: string;
+    /** What the check waits for, in one plain line. */
+    waitsFor?: string;
+}
+/** A text with each half of a broken character pair replaced: such a half is no text a file holds. */
+export declare function wellFormed(text: string): string;
+/** The front matter of a skill file as written here, between its two lines of dashes. */
+export declare function frontMatterOf(text: string): string;
+/**
+ * The skill file of an automation: the front matter, then the prompt. The description is the
+ * prompt's first line, cut short: it is what the row says the command does. Every text a person
+ * typed is written quoted, so it can change no other key of the front matter, and the check as a
+ * block where it can be, so it reads in the file as typed.
+ */
+export declare function automationSkill(automation: NewAutomation): string;
+/**
+ * The automation a file holds, when the file is what {@link automationSkill} writes for one;
+ * nothing for any other file: a skill somebody wrote, or an automation changed by hand since it
+ * was saved into something the tool does not write. What is read back, written again, is the
+ * file itself, so rewriting it loses nothing.
+ *
+ * What the description says may differ, while its line is a quoted text as the tool writes it:
+ * it is the prompt's first line, written anew with every save, so a person who changed that line
+ * of the prompt by hand still has an automation, with a description a line behind. A description
+ * written any other way is a person's, and the file a skill of theirs.
+ */
+export declare function automationOf(name: string, md: string): NewAutomation | undefined;
+/** What a file manager leaves in a folder a person only looked at: no part of a skill, and it goes with the folder. */
+export declare const FOLDER_LITTER = ".DS_Store";
+/** What saving an automation again writes beside its file before moving it over the file: left behind only by a save that was cut short, it is the tool's own, no part of a skill, and it goes with the next save or with the folder. */
+export declare const HALF_SAVED = "SKILL.md.new";
+/**
+ * Whether a skill's folder in the project is what saving a shared automation makes: a folder that
+ * is no link, holding the skill's file, no link either, and nothing else but what a file manager
+ * leaves behind and what a save of the tool's own that was cut short left. A skill that comes from a package is a link, and a skill with scripts beside its
+ * file holds more: neither is an automation, whatever its file says.
+ */
+export declare function standsAlone(repo: string, name: string): Promise<boolean>;
+/** Whether a path is a file and no link to one: writing or deleting a link would reach a file kept somewhere else. */
+export declare function isPlainFile(path: string): Promise<boolean>;
+//# sourceMappingURL=automation-file.d.ts.map

package/dist/automation-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automation-file.d.ts","sourceRoot":"","sources":["../src/automation-file.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AAEH,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAWD,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AA0BD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAuBjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAsBhF;AAsBD,uHAAuH;AACvH,eAAO,MAAM,aAAa,cAAc,CAAA;AAExC,yOAAyO;AACzO,eAAO,MAAM,UAAU,iBAAsB,CAAA;AAE7C;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU9E;AAED,sHAAsH;AACtH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKhE"}

package/dist/automation-file.js

@@ -0,0 +1,153 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { RUN_SKILLS_DIR, SKILL_FILE } from './names.js';
+/** How much of the prompt's first line stands as the skill's description, in characters. */
+const DESCRIPTION_MAX = 150;
+/** Characters a quoted value writes as an escape beyond what JSON escapes: DEL and the C1 controls, the two Unicode line ends, the byte order mark. */
+const SPECIALS = /[\u007f-\u009f\u2028\u2029\ufeff]/g;
+/** Characters a block cannot hold as typed: every control character but the line end, and the ones above. */
+const CONTROLS = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u2028\u2029\ufeff]/;
+/** A text with each half of a broken character pair replaced: such a half is no text a file holds. */
+export function wellFormed(text) {
+    return text.replace(/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g, '\ufffd');
+}
+/** The front matter of a skill file as written here, between its two lines of dashes. */
+export function frontMatterOf(text) {
+    return text.slice(4, text.indexOf('\n---\n', 4));
+}
+/**
+ * A text as a quoted value of the front matter: every character that could end the value, the
+ * line or the front matter is written as an escape, three dashes in a row among them, since a
+ * coding agent's reader ends the front matter at the first three dashes anywhere. Half of a
+ * broken character pair, which no file holds as text, is replaced. It reads back as the text.
+ */
+function quoted(text) {
+    return JSON.stringify(wellFormed(text))
+        .replace(SPECIALS, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)
+        .replaceAll('---', '--\\u002d');
+}
+/**
+ * Whether a check can stand in the file as a block, line for line as typed, the way the skills
+ * write theirs: no character a block would lose or read as layout (a control character, blanks at
+ * a line's end, blanks at its first line's start, where the block's indent is measured), and no
+ * three dashes. Any other check is written quoted, on one line.
+ */
+function fitsBlock(check) {
+    if (CONTROLS.test(check) || check.includes('---'))
+        return false;
+    const lines = check.split('\n');
+    return lines[0] === lines[0].trimStart() && lines.every(line => line === line.trimEnd());
+}
+/**
+ * The skill file of an automation: the front matter, then the prompt. The description is the
+ * prompt's first line, cut short: it is what the row says the command does. Every text a person
+ * typed is written quoted, so it can change no other key of the front matter, and the check as a
+ * block where it can be, so it reads in the file as typed.
+ */
+export function automationSkill(automation) {
+    const prompt = wellFormed(automation.prompt.trim());
+    // Cut by whole characters: half an emoji is no text.
+    const first = Array.from(prompt.split('\n')[0].trim());
+    const description = first.length > DESCRIPTION_MAX ? `${first.slice(0, DESCRIPTION_MAX - 1).join('')}…` : first.join('');
+    const when = automation.when === undefined ? undefined : wellFormed(automation.when.trim());
+    const lines = [
+        '---',
+        `name: ${automation.name}`,
+        `description: ${quoted(description)}`,
+        'disable-model-invocation: true',
+        // With neither a pace nor a check the schedule is an empty row, which the reader refuses in its own words.
+        automation.every === undefined && when === undefined && automation.waitsFor === undefined ? 'schedule: {}' : 'schedule:',
+        // A pace as the tool writes one stands as it is; anything else typed there is quoted, and the reader then says what is wrong with it.
+        ...(automation.every !== undefined ? [`  every: ${/^\d+(m|h|d|w|mo)$/.test(automation.every) ? automation.every : quoted(automation.every)}`] : []),
+        ...(automation.waitsFor !== undefined ? [`  waits-for: ${quoted(automation.waitsFor.trim())}`] : []),
+        ...(when === undefined ? [] : fitsBlock(when) ? ['  when: |-', ...when.split('\n').map((line) => (line === '' ? '' : `    ${line}`))] : [`  when: ${quoted(when)}`]),
+        '---',
+        '',
+        prompt,
+        '',
+    ];
+    return lines.join('\n');
+}
+/**
+ * The automation a file holds, when the file is what {@link automationSkill} writes for one;
+ * nothing for any other file: a skill somebody wrote, or an automation changed by hand since it
+ * was saved into something the tool does not write. What is read back, written again, is the
+ * file itself, so rewriting it loses nothing.
+ *
+ * What the description says may differ, while its line is a quoted text as the tool writes it:
+ * it is the prompt's first line, written anew with every save, so a person who changed that line
+ * of the prompt by hand still has an automation, with a description a line behind. A description
+ * written any other way is a person's, and the file a skill of theirs.
+ */
+export function automationOf(name, md) {
+    const end = md.startsWith('---\n') ? md.indexOf('\n---\n', 4) : -1;
+    if (end < 0)
+        return undefined;
+    let data;
+    try {
+        data = parseYaml(md.slice(4, end));
+    }
+    catch {
+        return undefined;
+    }
+    const schedule = isMap(data) ? data['schedule'] : undefined;
+    if (!isMap(schedule))
+        return undefined;
+    const { every, when } = schedule;
+    const waitsFor = schedule['waits-for'];
+    const automation = {
+        name,
+        prompt: md.slice(end + '\n---\n'.length).trim(),
+        ...(every !== undefined ? { every: String(every) } : {}),
+        ...(typeof when === 'string' ? { when } : {}),
+        ...(typeof waitsFor === 'string' ? { waitsFor } : {}),
+    };
+    // A file with no such description is nothing the tool wrote: what the tool writes always has one.
+    return butDescription(md) === butDescription(automationSkill(automation)) ? automation : undefined;
+}
+/** A file without its description, where the tool writes it: on the third line, after the opening dashes and the name, as one quoted text and nothing after it. Nothing for a file with no such line. */
+function butDescription(md) {
+    const lines = md.split('\n');
+    const said = lines[2]?.startsWith('description: "') ? lines[2].slice('description: '.length) : undefined;
+    return said !== undefined && isQuoted(said) ? [...lines.slice(0, 2), ...lines.slice(3)].join('\n') : undefined;
+}
+/** Whether a text is one quoted text as {@link quoted} writes it, whole: what follows a closing quote, a comment, is a person's writing. */
+function isQuoted(text) {
+    try {
+        return typeof JSON.parse(text) === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+function isMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** What a file manager leaves in a folder a person only looked at: no part of a skill, and it goes with the folder. */
+export const FOLDER_LITTER = '.DS_Store';
+/** What saving an automation again writes beside its file before moving it over the file: left behind only by a save that was cut short, it is the tool's own, no part of a skill, and it goes with the next save or with the folder. */
+export const HALF_SAVED = `${SKILL_FILE}.new`;
+/**
+ * Whether a skill's folder in the project is what saving a shared automation makes: a folder that
+ * is no link, holding the skill's file, no link either, and nothing else but what a file manager
+ * leaves behind and what a save of the tool's own that was cut short left. A skill that comes from a package is a link, and a skill with scripts beside its
+ * file holds more: neither is an automation, whatever its file says.
+ */
+export async function standsAlone(repo, name) {
+    const folder = join(repo, RUN_SKILLS_DIR, name);
+    try {
+        const [dir, entries] = await Promise.all([lstat(folder), readdir(folder)]);
+        // The leftover of a save is a file: a link or a folder of that name is somebody's, and writing through it would reach something kept elsewhere.
+        const halfSaved = !entries.includes(HALF_SAVED) || (await isPlainFile(join(folder, HALF_SAVED)));
+        return dir.isDirectory() && halfSaved && entries.every(entry => entry === SKILL_FILE || entry === FOLDER_LITTER || entry === HALF_SAVED) && (await isPlainFile(join(folder, SKILL_FILE)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a path is a file and no link to one: writing or deleting a link would reach a file kept somewhere else. */
+export async function isPlainFile(path) {
+    return lstat(path).then(stat => stat.isFile(), () => false);
+}
+//# sourceMappingURL=automation-file.js.map

package/dist/automation-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automation-file.js","sourceRoot":"","sources":["../src/automation-file.ts"],"names":[],"mappings":"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"}

package/dist/automation.d.ts

@@ -0,0 +1,189 @@
+import { writeFile } from 'node:fs/promises';
+import { type GitRunner } from '@openagt/agent-data';
+import { type NewAutomation } from './automation-file.js';
+import { runCheck } from './tick.js';
+/**
+ * A person's own automation: a prompt they wrote, saved as a command skill of the project, so it
+ * has a row like any skill's and the tick treats it as one. The skill's text is the
+ * prompt; its front matter makes it a command (`disable-model-invocation`) and carries the
+ * `schedule` the person picked: a pace, a check, or both.
+ *
+ * Shared with the project, it is a file in the person's checkout, in the folder the coding agent
+ * that runs scheduled commands reads. Like any skill a person writes there, it is no command to a
+ * run until it is on the commit a run's checkout starts from: the person commits it and brings it
+ * there. Kept on this machine alone, it is the same file in the tool's own folder, and a run is
+ * handed its text with a prompt that is the automation's name.
+ *
+ * Saved, it can be shown, saved again with other words under the same name, and removed: only
+ * while its file still reads as the tool writes one (`automation-file.ts`).
+ */
+export type AddRefusal = {
+    ok: false;
+    reason: 'bad-name';
+    detail: string;
+} | {
+    ok: false;
+    reason: 'no-prompt';
+} | {
+    ok: false;
+    reason: 'long-prompt';
+    detail: string;
+} | {
+    ok: false;
+    reason: 'bad-schedule';
+    detail: string;
+} | {
+    ok: false;
+    reason: 'taken';
+    folder: string;
+};
+/**
+ * Why an automation cannot be saved as written, or nothing: its name, its prompt, and its
+ * schedule by the very reader the tick reads skills with. What the reader reads back has to be
+ * what was typed, and the file has to read the same to a coding agent, whose reader ends the
+ * front matter at the first three dashes it meets anywhere.
+ */
+export declare function automationProblem(automation: NewAutomation): AddRefusal | undefined;
+/** Where an automation's file was written, new or anew, and what whoever asked needs to say about it. */
+export interface Written {
+    ok: true;
+    command: string;
+    /** The file written, from the repository root. */
+    file: string;
+    /** What a run's checkout starts from, as git names it: where a shared automation's file has to get to before its command can start. */
+    startsFrom: string;
+    /** Whether it is kept on this machine alone: it needs no commit, and its command can start at once. */
+    onThisMachine?: true;
+    /** What the file says now, as {@link SavedAutomation.version} names it, when it was written anew: what the next save from the same place is held against. */
+    version?: string;
+}
+/**
+ * Save an automation, shared with the project or kept on this machine alone.
+ *
+ * Shared, it is a skill file of the project, which the person commits; like any skill, its command
+ * starts no run before the file is on the commit a run's checkout starts from. Kept on this
+ * machine, it is one file in the tool's own folder, hidden from git like the state: nobody else
+ * gets the row, nothing is to commit, and a run of it is handed its text.
+ *
+ * Refused when it cannot be read back as written, and when its name is taken, whatever its
+ * capitals: by a skill in any folder a coding agent reads skills from, or by an automation kept on
+ * this machine. An automation never replaces either, and on a disk that ignores capitals `Foo` and
+ * `foo` are one name. A write that fails leaves no empty folder behind, shared or kept here.
+ */
+export declare function addAutomation(repo: string, automation: NewAutomation, git: GitRunner, opts?: {
+    onThisMachine?: boolean;
+    write?: typeof writeFile;
+}): Promise<Written | AddRefusal>;
+/** An automation where it is saved: what `show` answers, and what `edit` and `remove` act on. */
+export interface SavedAutomation {
+    automation: NewAutomation;
+    /** Its file, from the repository root. */
+    file: string;
+    /** Whether it is kept on this machine alone. */
+    onThisMachine?: true;
+    /** A name for what its file says now: a save may be held against it, so it does not write over a change made since. */
+    version: string;
+}
+/** Why a name is no automation the tool rewrites or removes. */
+export type NotAnAutomation = {
+    ok: false;
+    reason: 'not-an-automation';
+    detail: string;
+};
+/** Why an automation was not saved again: its file says something else than whoever asked last read. */
+export type ChangedSince = {
+    ok: false;
+    reason: 'changed-since';
+    detail: string;
+};
+/**
+ * The automation of that name, where it is saved, or why the tool leaves what has the name alone.
+ *
+ * The tool rewrites and removes only what it wrote, and the schedule says what that is
+ * (`editable`): a command whose file reads as the tool writes one, in the tool's own folder, or
+ * alone in a skill folder of the project that is no link. A skill a person or a package wrote, and
+ * an automation changed by hand into something the tool does not write, are edited and removed by
+ * hand: rewriting one from here would lose what the tool does not write. What the schedule does
+ * not list is left alone too, with the schedule's own reason when it has one.
+ */
+export declare function savedAutomation(repo: string, name: string): Promise<SavedAutomation | NotAnAutomation>;
+/** What `edit` changes of an automation: a part given takes the place of the file's, `null` takes a part out, and a part left out stays as the file says it. */
+export interface AutomationChange {
+    prompt?: string | undefined;
+    every?: string | null | undefined;
+    when?: string | null | undefined;
+    waitsFor?: string | null | undefined;
+}
+/**
+ * Save an automation again under its name, with a new prompt or a new schedule: its file is
+ * written anew, where it is, with what was given in place of what it said and the rest as it
+ * was. What a check waits for goes out with the check, unless it is given too. Its name stays,
+ * and a run is counted by the name, so its past runs, its switch and a person's other picks for
+ * it stay its own.
+ *
+ * A shared one is a file of the project: the change is the person's to commit, and a run reads
+ * the prompt from the commit its checkout starts from, so it is told the new words only once the
+ * change is there, while the tick reads the new pace and the new check from the person's checkout
+ * at once. One kept on this machine has only its file: the next tick reads all of it.
+ *
+ * Refused for a name that is no automation the tool wrote ({@link savedAutomation}), and for what
+ * could not be saved new either ({@link automationProblem}, the length of a text kept here). With
+ * `was`, the version whoever asks last read, it is refused too when the file says something else
+ * by now: a form opened a while ago does not write over a change made to the file by hand since.
+ */
+export declare function editAutomation(repo: string, name: string, change: AutomationChange, git: GitRunner, opts?: {
+    write?: typeof writeFile;
+    was?: string;
+}): Promise<Written | AddRefusal | NotAnAutomation | ChangedSince>;
+/** What removing an automation did, and what whoever asked needs to say about it. */
+export type Removed = {
+    ok: true;
+    command: string; /** The file that was deleted, from the repository root. */
+    file: string;
+} & ({
+    /** Kept on this machine alone: it was in no git, and nothing of it is left anywhere. */
+    onThisMachine: true;
+} | {
+    /**
+     * What git still holds of a shared one's file: `committed`, the file is in a commit, so the
+     * deletion is a change of the person's to commit and git can bring the file back; `staged`,
+     * it was added to the index and never committed, so a commit made now would still add it;
+     * `nothing`, git never knew the file, and it cannot be brought back; `unknown`, git could
+     * not be asked.
+     */
+    git: 'committed' | 'staged' | 'nothing' | 'unknown';
+    /** What a run's checkout starts from, as git names it: until the deletion is there, everyone else who has the project keeps the command. */
+    startsFrom: string;
+});
+/**
+ * Remove an automation: its file is deleted, and the folder that held it alone, with what a file
+ * manager left beside it. Nothing is committed, and nothing git holds is changed: the deletion of
+ * a shared one is a change of the person's where the file is in a commit, and everyone else keeps
+ * the command until the deletion reaches them. What was never committed, a shared one's file or
+ * its last changes, and all of one kept on this machine, cannot be brought back. The records of
+ * its past runs stay.
+ *
+ * Refused for a name that is no automation the tool wrote ({@link savedAutomation}).
+ */
+export declare function removeAutomation(repo: string, name: string, git: GitRunner): Promise<Removed | NotAnAutomation>;
+/** What trying a check answered. */
+export interface Tried {
+    /** The time the check was given as `$LAST_RUN`. */
+    lastRun: string;
+    /** Whether the check ran to its end without an error. */
+    ran: boolean;
+    /** Whether what it printed would start an agent. */
+    due: boolean;
+    /** What it printed, cut as a run is handed it, with the line that says it was cut. */
+    printed: string;
+    /** Why it did not run, when it did not: that it took too long, or the last line of what it said went wrong. */
+    error?: string;
+}
+/**
+ * Run a check once, as the tick would, and say what it printed and whether an agent would start:
+ * nothing is saved and nothing is started. It asks what is new since a day ago. A try has less
+ * time than a tick gives a check ({@link TRY_TIMEOUT_MS}): whoever asks, a dashboard, waits for
+ * the answer, and gives up before a tick would.
+ */
+export declare function tryCheck(repo: string, shell: string, now: Date, check?: typeof runCheck, budgetMs?: number): Promise<Tried>;
+//# sourceMappingURL=automation.d.ts.map

package/dist/automation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automation.d.ts","sourceRoot":"","sources":["../src/automation.ts"],"names":[],"mappings":"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"}